{ "openapi": "3.1.1", "info": { "title": "Chartmetric Developer API", "description": "Public API documentation for the Chartmetric Developer API.\n\n## Credit consumption\n\nOn the Prepaid API plan every request consumes API credits. Most endpoints cost\n**1 credit** per request. Premium endpoints — labelled `💎 Premium` in their title —\nreturn higher-cost audience and playlist data and consume **2 credits** per request:\n\n- `GET /api/artist/{id}/instagram-audience-stats`\n- `GET /api/artist/{id}/instagram-audience-stats/dates`\n- `GET /api/artist/{id}/social-audience-stats`\n- `GET /api/artist/{id}/tiktok-audience-stats`\n- `GET /api/artist/{id}/tiktok-influencer-stats`\n- `GET /api/artist/{id}/tiktok-top-influencers`\n- `GET /api/artist/{id}/tiktok-top-videos`\n- `GET /api/artist/{id}/where-people-listen`\n- `GET /api/artist/{id}/youtube-audience-stats`\n- `GET /api/artist/{id}/{platform}/{status}/playlists`\n- `GET /api/brand/v2/{brandId}/audience`\n- `GET /api/track/{id}/tiktok-influencer-stats`\n- `GET /api/track/{id}/tiktok-top-influencers`\n- `GET /api/track/{id}/tiktok-top-sounds`\n- `GET /api/track/{id}/topVideos`\n\nCredits are deducted when the request is received, regardless of the number of rows\nreturned. Your remaining balance and the current per-endpoint costs are shown in your\nChartmetric account under Settings → API Usage. Fixed-rate monthly API plans are not\nbilled per request; they are limited by their request rate instead.", "version": "1.0.1671", "contact": { "name": "Chartmetric API Support", "email": "backend-engineering@chartmetric.com" } }, "servers": [ { "url": "https://api.chartmetric.com", "description": "Production" } ], "tags": [ { "name": "Token", "description": "Authentication. Exchange your refresh token for a short-lived access token, which must be sent as a bearer token on every other request." }, { "name": "Search", "description": "Search across Chartmetric entities. Endpoints resolve a free-text query to artists, tracks, albums, playlists and curators, with a dedicated search for social handles and profile URLs." }, { "name": "Genre", "description": "Chartmetric's genre taxonomy, used to filter artists, tracks and charts. Endpoints list all genres and return a single genre by ID." }, { "name": "City", "description": "Cities used for geographic breakdowns of audience and consumption data. Endpoints list the cities of a country and return the top artists or tracks in a city for a given platform." }, { "name": "Album", "description": "Albums, EPs and singles as released on streaming platforms, identified by a Chartmetric album ID. Endpoints cover album metadata, cross-platform ID lookup, the tracklist, per-platform stats, chart appearances, and the playlists the album is featured on." }, { "name": "Artist", "description": "Artists, the core entity in Chartmetric, identified by a Chartmetric artist ID. Endpoints cover metadata and platform URLs, cross-platform ID lookup, fan metrics and cached stat trends, artist rank and Cross-Platform Performance (CPP), catalog data (tracks, albums, chart appearances, playlists), audience demographics for Instagram, TikTok and YouTube plus Spotify listener geography, discovery lists (A&R, similar, related and neighboring artists), and career context such as milestones, news, live events, venues and TV appearances." }, { "name": "Brand", "description": "Brands tracked for sponsorship and partnership research. Endpoints list brand names, filter brands by interest category, and return the details of a single brand." }, { "name": "Charts", "description": "Charts collected from streaming, social and radio platforms — Spotify, Apple Music, iTunes, Amazon, Deezer, YouTube, TikTok, Shazam, Beatport, SoundCloud, Twitch, Pandora, Anghami, QQ Music and regional charts such as Circle, Hanteo, Melon and Line Music. Endpoints return chart rankings per platform and entity type (artist, track, album, video, sound, user), the Chartmetric score of a charted entity, and the supporting lookups for available chart dates, countries and genres." }, { "name": "Country", "description": "Country-level rankings. Endpoints return artist rankings for a country, broken down by area, ranking type and sub-area." }, { "name": "Curator", "description": "Playlist curators — the editorial and user accounts that own playlists on Spotify, Apple Music, Amazon, Deezer, YouTube and iTunes. Endpoints list curators per platform and return a curator's metadata, social and streaming URLs, follower metrics over time, and playlists." }, { "name": "Playlist", "description": "Playlists across Spotify, Apple Music, Amazon, Deezer, YouTube, iTunes and SoundCloud. Endpoints list playlists per platform and return playlist metadata, follower and position history, current or past tracklists, a snapshot for a specific date, similar playlists, the last time the playlist was updated, and the playlist journey of an artist, album or track." }, { "name": "Radio", "description": "Radio airplay data for artists and tracks. Endpoints return airplay time series, total airplay counts overall, by entity and by broadcast market, and the radio station list for a country." }, { "name": "Track", "description": "Tracks (recordings), identified by a Chartmetric track ID or a platform ID such as an ISRC or Spotify ID. Endpoints cover track metadata, cross-platform ID lookup, per-platform stats, chart appearances, playlist placements and dated snapshots, playlist stream estimates (single and batch), related tracks, milestones, filtered track lists, and TikTok video and YouTube Shorts performance." }, { "name": "Festival", "description": "Music festivals tracked by Chartmetric. Endpoints return the list of festivals." }, { "name": "Event", "description": "Live events tied to a venue. Endpoints return the events scheduled at a given venue." }, { "name": "SNS", "description": "Deep social data for the social accounts linked to Chartmetric entities. Endpoints return post-level performance, such as the top Instagram posts and reels of an artist." }, { "name": "Venue", "description": "Venues used for live-event and touring data. Endpoints return the list of venues." } ], "paths": { "/api/token": { "post": { "summary": "Create API Access Token", "tags": [ "Token" ], "operationId": "createAccessToken", "description": "Exchange a refresh token for a short-lived JWT access token used to authorize Developer API requests.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "refreshtoken": { "type": "string", "description": "Long-lived refresh token issued at signup; used to mint a fresh short-lived access token.", "examples": [ "example" ] } }, "required": [ "refreshtoken" ], "additionalProperties": false, "examples": [ { "refreshtoken": "example" } ] }, "examples": { "default": { "value": { "refreshtoken": "example" } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "Short-lived JWT access token to use as `Authorization: Bearer ` on subsequent Developer API calls." }, "expires_in": { "type": "integer", "description": "Number of seconds after which the access token expires." }, "refresh_token": { "type": "string", "description": "Long-lived refresh token for obtaining a new access token (echoes the token supplied in the request)." }, "scope": { "type": "string", "description": "Level of access granted by the token. Currently always `api`." } }, "required": [ "token", "expires_in", "refresh_token", "scope" ], "additionalProperties": false }, "examples": { "default": { "value": { "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "expires_in": 3600, "refresh_token": "", "scope": "api" } } } } } } } } }, "/api/search": { "get": { "summary": "Chartmetric Search", "tags": [ "Search" ], "operationId": "searchAll", "description": "Search tracks, albums, artists, curators, playlists, stations, cities, songwriters, and more with a single query. Also accepts DSP URLs (Spotify, Apple Music, Deezer, etc.). The shape below is the default (`type=all`) response; narrowing via `type=artists|tracks|playlists|...` returns only the matching bucket. Enabling `beta=true` switches to the beta global-search engine which returns `suggestions` entries instead.", "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string", "oneOf": [ { "type": "string", "maxLength": 100 } ], "description": "Search query. Free text matched across artists, tracks, albums, playlists, curators, stations, cities, and songwriters; or a streaming/social URL to look up a single entity by its native ID." }, "required": true, "description": "Search query. Free text matched across artists, tracks, albums, playlists, curators, stations, cities, and songwriters; or a streaming/social URL to look up a single entity by its native ID.", "examples": { "default": { "value": "example" } } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum number of items to return per request.", "default": 10 }, "required": false, "description": "Maximum number of items to return per request." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, "required": false, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "all", "artists", "tracks", "playlists", "curators", "albums", "stations", "cities", "songwriters" ], "description": "Restrict the search to a single entity bucket. One of `all`, `artists`, `tracks`, `playlists`, `curators`, `albums`, `stations`, `cities`, `songwriters`. Defaults to `all`.", "default": "all" }, "required": false, "description": "Restrict the search to a single entity bucket. One of `all`, `artists`, `tracks`, `playlists`, `curators`, `albums`, `stations`, `cities`, `songwriters`. Defaults to `all`." }, { "name": "beta", "in": "query", "schema": { "type": "boolean", "description": "If true, use the beta global-search engine which returns a flat `suggestions` list with `match_strength` and `target` per item instead of bucketed results.", "default": false }, "required": false, "description": "If true, use the beta global-search engine which returns a flat `suggestions` list with `match_strength` and `target` per item instead of bucketed results." }, { "name": "platforms", "in": "query", "schema": { "oneOf": [ { "type": "array", "items": { "type": "string", "enum": [ "cm", "spotify", "itunes", "applemusic", "deezer", "amazon", "youtube", "tidal", "soundcloud", "acr" ] } } ], "description": "Restrict beta search to these platforms. Only valid when `beta=true`. One or more of `cm`, `spotify`, `itunes`, `applemusic`, `deezer`, `amazon`, `youtube`, `tidal`, `soundcloud`, `acr`." }, "required": false, "description": "Restrict beta search to these platforms. Only valid when `beta=true`. One or more of `cm`, `spotify`, `itunes`, `applemusic`, `deezer`, `amazon`, `youtube`, `tidal`, `soundcloud`, `acr`." }, { "name": "triggerCitiesOnly", "in": "query", "schema": { "type": "boolean", "description": "If true, restrict city results to Chartmetric Trigger Cities. Available for both beta and non-beta search.", "default": false }, "required": false, "description": "If true, restrict city results to Chartmetric Trigger Cities. Available for both beta and non-beta search." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "object", "properties": { "artists": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric artist ID." }, "name": { "type": "string", "description": "Artist name." }, "image_url": { "type": [ "string", "null" ], "description": "Artist image URL." }, "isni": { "type": [ "string", "null" ], "description": "International Standard Name Identifier (ISNI) of the artist." }, "sp_followers": { "type": [ "integer", "null" ], "minimum": 0, "description": "Spotify follower count." }, "sp_monthly_listeners": { "type": [ "integer", "null" ], "minimum": 0, "description": "Spotify monthly listener count." }, "cm_artist_score": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric artist score (composite popularity metric)." } }, "required": [ "id", "name" ] }, "description": "Artist matches." }, "playlists": { "type": "object", "properties": { "spotify": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric playlist ID." }, "name": { "type": "string", "description": "Playlist name." }, "image_url": { "type": [ "string", "null" ], "description": "Playlist cover image URL." }, "owner_name": { "type": [ "string", "null" ], "description": "Playlist owner / curator's display name." } }, "required": [ "id", "name" ] }, "description": "Spotify playlist matches." }, "applemusic": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric playlist ID." }, "name": { "type": "string", "description": "Playlist name." }, "image_url": { "type": [ "string", "null" ], "description": "Playlist cover image URL." }, "owner_name": { "type": [ "string", "null" ], "description": "Playlist owner / curator's display name." } }, "required": [ "id", "name" ] }, "description": "Apple Music playlist matches." }, "deezer": { "type": "array", "items": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "integer", "minimum": 0, "maximum": 2147483647 } ], "description": "Chartmetric playlist ID. May be returned as a string for platform-native IDs." }, "name": { "type": "string", "description": "Playlist name." }, "image_url": { "type": [ "string", "null" ], "description": "Playlist cover image URL." }, "owner_name": { "type": [ "string", "null" ], "description": "Playlist owner / curator's display name." } }, "required": [ "id", "name" ] }, "description": "Deezer playlist matches." }, "amazon": { "type": "array", "items": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "integer", "minimum": 0, "maximum": 2147483647 } ], "description": "Chartmetric playlist ID. May be returned as a string for platform-native IDs." }, "name": { "type": "string", "description": "Playlist name." }, "image_url": { "type": [ "string", "null" ], "description": "Playlist cover image URL." }, "owner_name": { "type": [ "string", "null" ], "description": "Playlist owner / curator's display name." } }, "required": [ "id", "name" ] }, "description": "Amazon Music playlist matches." }, "youtube": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "YouTube playlist ID." }, "name": { "type": "string", "description": "Playlist name." }, "image_url": { "type": [ "string", "null" ], "description": "Playlist cover image URL." } }, "required": [ "id", "name" ] }, "description": "YouTube playlist matches." }, "soundcloud": { "type": "array", "items": {}, "description": "SoundCloud playlist matches." } }, "required": [ "spotify", "applemusic", "deezer", "amazon", "youtube", "soundcloud" ], "description": "Playlist matches grouped by streaming platform." }, "tracks": { "type": "array", "items": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "description": "Chartmetric track ID. May be returned as a string or number." }, "name": { "type": "string", "description": "Track name." }, "image_url": { "type": [ "string", "null" ], "description": "Track cover image URL." }, "isrc": { "type": [ "string", "null" ], "description": "International Standard Recording Code identifying the track." }, "artist_names": { "type": "array", "items": { "type": "string" }, "description": "Artist names credited on the track." } }, "required": [ "id", "name", "artist_names" ] }, "description": "Track matches." }, "curators": { "type": "object", "properties": { "spotify": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric curator ID." }, "name": { "type": [ "string", "null" ], "description": "Curator's display name." }, "image_url": { "type": [ "string", "null" ], "description": "Curator profile image URL." } }, "required": [ "id" ] }, "description": "Spotify curator matches." }, "applemusic": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric curator ID." }, "name": { "type": [ "string", "null" ], "description": "Curator's display name." }, "image_url": { "type": [ "string", "null" ], "description": "Curator profile image URL." } }, "required": [ "id" ] }, "description": "Apple Music curator matches." }, "deezer": { "type": "array", "items": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "integer", "minimum": 0, "maximum": 2147483647 } ], "description": "Chartmetric curator ID. May be returned as a string for platform-native IDs." }, "name": { "type": [ "string", "null" ], "description": "Curator's display name." }, "image_url": { "type": [ "string", "null" ], "description": "Curator profile image URL." } }, "required": [ "id" ] }, "description": "Deezer curator matches." }, "amazon": { "type": "array", "items": {}, "description": "Amazon Music curator matches." }, "youtube": { "type": "array", "items": {}, "description": "YouTube curator matches." } }, "required": [ "spotify", "applemusic", "deezer", "amazon", "youtube" ], "description": "Curator matches grouped by streaming platform." }, "albums": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric album ID." }, "name": { "type": "string", "description": "Album name." }, "image_url": { "type": [ "string", "null" ], "description": "Album cover image URL." }, "label": { "type": [ "string", "null" ], "description": "Record label that released the album." } }, "required": [ "id", "name" ] }, "description": "Album matches." }, "stations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric station ID." }, "name": { "type": "string", "description": "Radio/SiriusXM station name." }, "genre": { "type": [ "string", "null" ], "description": "Genre format of the station." }, "image_url": { "type": [ "string", "null" ], "description": "Station logo or image URL." }, "station_city": { "type": [ "string", "null" ], "description": "City where the station is broadcast from." }, "country": { "type": [ "string", "null" ], "description": "Country where the station is broadcast from." } }, "required": [ "id", "name" ] }, "description": "Radio and SiriusXM station matches." }, "labels": { "type": "array", "items": {}, "description": "Record label matches." }, "cities": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric city ID." }, "name": { "type": "string", "description": "City name." }, "name_ascii": { "type": [ "string", "null" ], "description": "ASCII-only transliteration of the city name." }, "population": { "type": [ "number", "null" ], "format": "float", "description": "City population. Used to disambiguate same-named cities across other endpoints." }, "country": { "type": [ "string", "null" ], "description": "Country name." }, "code2": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB')." }, "province": { "type": [ "string", "null" ], "description": "State, province, or first-level administrative subdivision." }, "trigger_city": { "type": "boolean", "description": "Whether the city is classified as a Chartmetric Trigger City." } }, "required": [ "id", "name" ] }, "description": "City matches." }, "countries": { "type": "array", "items": {}, "description": "Country matches." }, "songwriters": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "description": "Songwriter name." }, "doc_id": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric songwriter ID." }, "artistName": { "type": [ "string", "null" ], "description": "Linked artist name when the songwriter also performs." }, "image_url": { "type": [ "string", "null" ], "description": "Songwriter image URL." } }, "required": [ "doc_id" ] }, "description": "Songwriter matches." }, "genres": { "type": "array", "items": {}, "description": "Genre matches." }, "festivals": { "type": "array", "items": {}, "description": "Festival matches." } }, "required": [ "artists", "playlists", "tracks", "curators", "albums", "stations", "labels", "cities", "songwriters", "genres", "festivals" ] } }, "required": [ "obj" ], "additionalProperties": false }, "examples": { "default": { "value": { "obj": { "artists": [ { "id": 3963, "name": "Ariana Grande", "image_url": "https://i.scdn.co/image/ab6761610000e5eb40b5c07ab77b6b1a9075fdc0", "isni": "0000000059110272", "sp_followers": 97135043, "sp_monthly_listeners": 80733093, "cm_artist_score": 495952 } ], "playlists": { "spotify": [ { "id": 741236, "name": "Ariana Grande: Best Of", "image_url": "https://i.scdn.co/image/ab67706c0000bebb4d5b3fbd576a2254f137f5e1", "owner_name": "arianagrandeofficial" } ], "applemusic": [], "deezer": [ { "id": "1147053693", "name": "Ariana Grande Selection", "image_url": "https://api.deezer.com/playlist/1147053693/image", "owner_name": "Tigo El Salvador" } ], "amazon": [], "youtube": [], "soundcloud": [] }, "tracks": [ { "id": "27590886", "name": "Ariana", "image_url": "https://i.scdn.co/image/9fa1a27e9e43b48a822e23285d1a13b64f74d311", "isrc": "GBKPL1977961", "artist_names": [ "Tony Anderson" ] } ], "curators": { "spotify": [ { "id": 59081, "name": "arianagrandeofficial", "image_url": null } ], "applemusic": [], "deezer": [], "amazon": [], "youtube": [] }, "albums": [ { "id": 15091594, "name": "Ariana", "image_url": "https://i.scdn.co/image/ab67616d0000b2737b0314e32f28c3aa6bcab762", "label": "Dfideliz" } ], "stations": [], "labels": [], "cities": [ { "id": 16166, "name": "Ariana", "name_ascii": "Ariana", "population": 97687, "country": "Tunisia", "code2": "TN", "province": null, "trigger_city": false } ], "countries": [], "songwriters": [ { "name": "Nicole Ariana", "doc_id": 1564636, "artistName": "Nicole Ariana", "image_url": null } ], "genres": [], "festivals": [] } } } } } } } } } }, "/api/search/social": { "get": { "summary": "Chartmetric Social Search", "tags": [ "Search" ], "operationId": "searchSocial", "description": "Search artists, curators, radio/SiriusXM stations, and songwriters by their social media URLs. DSP links (Spotify, Apple Music, etc.) should be resolved via `/api/{entity}/{type}/{id}/get-ids` instead.", "parameters": [ { "name": "url", "in": "query", "schema": { "type": "string", "description": "Social media URL to resolve (Instagram, TikTok, X/Twitter, YouTube, Facebook, etc.). DSP links should be resolved via `/api/{entity}/{type}/{id}/get-ids` instead." }, "required": true, "description": "Social media URL to resolve (Instagram, TikTok, X/Twitter, YouTube, Facebook, etc.). DSP links should be resolved via `/api/{entity}/{type}/{id}/get-ids` instead.", "examples": { "default": { "value": "https://example.com" } } }, { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "all", "artists", "radio", "siriusxm", "songwriters", "curators" ], "description": "Restrict the search to a single entity type. One of `all`, `artists`, `radio`, `siriusxm`, `songwriters`, `curators`. Defaults to `all`.", "default": "all" }, "required": false, "description": "Restrict the search to a single entity type. One of `all`, `artists`, `radio`, `siriusxm`, `songwriters`, `curators`. Defaults to `all`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "array", "items": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "description": "Chartmetric ID of the resolved entity. Numeric for artist/curator, string for platform-native IDs (e.g. SiriusXM channel slug)." }, "type": { "type": [ "string", "null" ], "description": "Entity type of the match (e.g. `artist`, `curator`, `radio`, `siriusxm`, `songwriter`)." }, "name": { "type": [ "string", "null" ], "description": "Entity name. Currently populated reliably only for artists." }, "image_url": { "type": [ "string", "null" ], "description": "Entity image URL. Currently populated reliably only for artists." } }, "required": [ "id" ] } } }, "required": [ "obj" ], "additionalProperties": false }, "examples": { "default": { "value": { "obj": [ { "id": 2762, "type": "artist", "name": "Taylor Swift", "image_url": "https://i.scdn.co/image/ab67616100005174f173136b94ae2f75f49f8b2b" } ] } } } } } } } } }, "/api/genres": { "get": { "summary": "List Chartmetric Genres", "tags": [ "Genre" ], "operationId": "listGenres", "description": "List Chartmetric genres, optionally filtered by `name`. Pass `isLegacy=true` to receive the legacy `genre` taxonomy instead of `genre_v2`.", "parameters": [ { "name": "name", "in": "query", "schema": { "type": "string", "description": "Case-insensitive substring filter on genre name; omit to return all genres." }, "required": false, "description": "Case-insensitive substring filter on genre name; omit to return all genres." }, { "name": "isLegacy", "in": "query", "schema": { "type": "boolean", "description": "When true, returns the legacy `genre` taxonomy; when false (default), returns the modern `genre_v2` taxonomy.", "default": false }, "required": false, "description": "When true, returns the legacy `genre` taxonomy; when false (default), returns the modern `genre_v2` taxonomy." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Chartmetric genre ID." }, "name": { "type": "string", "description": "Genre name (e.g. `K-Pop`, `Mandopop`)." } }, "required": [ "id", "name" ] } } }, "required": [ "obj" ], "additionalProperties": false }, "examples": { "default": { "value": { "obj": [ { "id": 462862, "name": "Devotional & Spiritual" }, { "id": 462863, "name": "Mandopop" } ] } } } } } } } } }, "/api/genres/{id}": { "get": { "summary": "Get Genre by ID", "tags": [ "Genre" ], "operationId": "getGenreById", "description": "Fetch a single Chartmetric genre by its ID.", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric genre ID." }, "required": true, "description": "Chartmetric genre ID.", "examples": { "default": { "value": 1 } } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "description": "Chartmetric genre ID." }, "name": { "type": "string", "description": "Genre name (e.g. `K-Pop`)." }, "type": { "type": "string", "enum": [ "genre", "genre_v2" ], "description": "Taxonomy the genre belongs to: `genre_v2` is the modern Chartmetric taxonomy, `genre` is the legacy taxonomy." }, "source": { "type": "string", "description": "Origin of the genre record (e.g. `cm` for Chartmetric-curated, `spotify` for Spotify-derived sub-genres)." } }, "required": [ "id", "name", "type", "source" ] } }, "additionalProperties": false }, "examples": { "default": { "value": { "obj": { "id": 462925, "name": "K-Pop", "type": "genre_v2", "source": "cm" } } } } } } } } } }, "/api/cities": { "get": { "summary": "List Cities by Country", "tags": [ "City" ], "operationId": "listCities", "description": "List cities within a country (ISO 3166-1 alpha-2 `country_code`). Optionally narrow to a single city by `city_id`.", "parameters": [ { "name": "country_code", "in": "query", "schema": { "type": "string", "minLength": 2, "maxLength": 2, "enum": [ "AD", "AE", "AF", "AG", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BM", "BN", "BO", "BR", "BS", "BT", "BW", "BY", "BZ", "CA", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IQ", "IR", "IS", "IT", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NG", "NI", "NL", "NO", "NP", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TG", "TH", "TJ", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "US", "UY", "UZ", "VA", "VC", "VE", "VI", "VN", "VU", "WF", "WS", "XK", "XW", "YE", "YT", "ZA", "ZM", "ZW" ], "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB')." }, "required": true, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB').", "examples": { "default": { "value": "AD" } } }, { "name": "city_id", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric city ID; narrows the result set to a single city." }, "required": false, "description": "Chartmetric city ID; narrows the result set to a single city." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "array", "items": { "type": "object", "properties": { "city_id": { "type": "integer", "description": "Chartmetric city ID." }, "city_name": { "type": "string", "description": "City name as stored in Chartmetric." }, "latitude": { "type": [ "number", "null" ], "format": "float", "description": "City latitude in decimal degrees (WGS84)." }, "longitude": { "type": [ "number", "null" ], "format": "float", "description": "City longitude in decimal degrees (WGS84)." }, "population": { "type": [ "integer", "null" ], "description": "Estimated city population." }, "province": { "type": [ "string", "null" ], "description": "Province, state, or first-level administrative subdivision the city belongs to." }, "locality": { "type": [ "string", "null" ], "description": "Locality (typically the same as `city_name`, occasionally a parent locality)." }, "country": { "type": [ "string", "null" ], "description": "Country name the city belongs to." }, "image_url": { "type": [ "string", "null" ], "description": "URL of a representative image for the city, when available." }, "iso3": { "type": [ "string", "null" ], "minLength": 3, "maxLength": 3, "description": "ISO 3166-1 alpha-3 country code of the city's country (3 letters, e.g. 'USA', 'BRA')." } }, "required": [ "city_id", "city_name" ] } } }, "required": [ "obj" ], "additionalProperties": false }, "examples": { "default": { "value": { "obj": [ { "city_id": 11778, "city_name": "Culpeper", "latitude": 38.4705, "longitude": -78.0001, "population": 19986, "province": null, "locality": "Culpeper", "country": "United States", "image_url": null, "iso3": "USA" } ] } } } } } } } } }, "/api/album/{id}/{type}/charts": { "get": { "summary": "Album Charts", "tags": [ "Album" ], "operationId": "getAlbumCharts", "description": "Chart history for an album on a platform (`applemusic`, `itunes`, or `amazon`). Date range accepts up to 365 days between `since` and `until`.", "parameters": [ { "name": "type", "in": "path", "schema": { "type": "string", "enum": [ "applemusic", "itunes", "amazon" ], "description": "Chart source platform. One of `applemusic`, `itunes`, or `amazon`." }, "required": true, "description": "Chart source platform. One of `applemusic`, `itunes`, or `amazon`.", "examples": { "default": { "value": "applemusic" } } }, { "name": "id", "in": "path", "schema": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric album ID." }, "required": true, "description": "Chartmetric album ID.", "examples": { "default": { "value": 1 } } }, { "name": "since", "in": "query", "schema": { "type": "string", "format": "date", "description": "Start date in ISO format (e.g. '2025-11-01'). Defaults to 180 days ago.", "default": "2026-05-09" }, "required": false, "description": "Start date in ISO format (e.g. '2025-11-01'). Defaults to 180 days ago." }, { "name": "until", "in": "query", "schema": { "type": "string", "format": "date", "description": "End date in ISO format (e.g. '2025-11-15'). Defaults to today; must be at most 365 days after `since`.", "default": "2026-11-05" }, "required": false, "description": "End date in ISO format (e.g. '2025-11-15'). Defaults to today; must be at most 365 days after `since`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "object", "properties": { "data": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "itunes_album_id": { "type": [ "string", "null" ], "description": "iTunes album ID at the time the chart was recorded." }, "rank": { "type": [ "integer", "null" ], "description": "Chart position on the recorded date." }, "added_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Date the chart row was recorded." }, "code2": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code of the chart (e.g. 'US')." }, "genre": { "type": [ "string", "null" ], "description": "Chart genre name." }, "gnp": { "type": [ "string", "null" ], "description": "Chart GNP segment value." }, "pre_rank": { "type": [ "integer", "null" ], "description": "Chart position on the previous recorded date." }, "peak_rank": { "type": [ "integer", "null" ], "description": "Best (lowest-numbered) chart position observed." }, "peak_date": { "type": [ "string", "null" ], "format": "date-time", "description": "Date `peak_rank` was achieved." }, "id": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Chartmetric album ID. Same value as `cm_album`." }, "name": { "type": [ "string", "null" ], "description": "Album name." }, "release_date": { "type": [ "string", "null" ], "format": "date-time", "description": "Album release date." }, "copyright": { "type": [ "string", "null" ], "description": "Album copyright statement." }, "num_track": { "type": [ "string", "null" ], "description": "Number of tracks on the album, returned as a string." }, "upc": { "type": [ "string", "null" ], "description": "Universal Product Code identifying the release." }, "description": { "type": [ "string", "null" ], "description": "Album description." }, "is_single": { "type": [ "boolean", "null" ], "description": "True when the release is classified as a single." }, "artwork_url": { "type": [ "string", "null" ], "description": "Album artwork image URL." }, "label": { "type": [ "string", "null" ], "description": "Record label that released the album." }, "genres": { "type": [ "string", "null" ], "description": "Comma-separated list of album genres." }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Date the album row was created in Chartmetric." }, "modified_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Date the album row was last modified in Chartmetric." }, "cm_album": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Chartmetric album ID." }, "storefronts": { "type": "array", "items": { "type": "string" }, "description": "ISO 3166-1 alpha-2 country codes where the album is available." }, "itunes_album_ids": { "type": "array", "items": { "type": "string" }, "description": "iTunes album IDs associated with this album." }, "artists": { "type": "array", "items": { "type": "object", "properties": { "itunes_artist_id": { "type": [ "integer", "null" ], "description": "iTunes artist ID." }, "name": { "type": [ "string", "null" ], "description": "Artist name." }, "cm_artist": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Chartmetric artist ID." } } }, "description": "Artists credited on the album." } } }, "description": "Chart history rows for the album, ordered by `added_at`." }, "length": { "type": "integer", "minimum": 0, "description": "Total number of rows in `data`." } }, "required": [ "length" ] } }, "additionalProperties": false }, "examples": { "default": { "value": { "obj": { "data": [ { "itunes_album_id": "1450330588", "rank": 84, "added_at": "2020-03-04T08:00:00.000Z", "code2": "US", "genre": "All Genres", "gnp": "8510700.00", "pre_rank": 80, "peak_rank": 1, "peak_date": "2019-02-08T08:00:00.000Z", "id": 3058232, "name": "thank u, next", "release_date": "2019-02-08T08:00:00.000Z", "copyright": "(P) 2019 Republic Records, a division of UMG Recordings, Inc.", "num_track": "12", "upc": "602577464980", "description": null, "is_single": false, "artwork_url": "https://is5-ssl.mzstatic.com/image/thumb/Music124/v4/4e/26/d5/4e26d5f3-2d62-1b5c-689a-e8de4e6f3797/00602577465284.rgb.jpg/160x160bb.jpeg", "label": "Republic Records", "genres": "Pop,Music", "created_at": null, "modified_at": "2020-09-17T03:10:01.823Z", "cm_album": 3533190, "storefronts": [ "AU", "JP", "LA", "NO", "US" ], "itunes_album_ids": [ "1450330588" ], "artists": [ { "itunes_artist_id": 412778295, "name": "Ariana Grande", "cm_artist": 3963 } ] } ], "length": 175 } } } } } } } } } }, "/api/album/{type}/{id}/get-ids": { "get": { "summary": "Get Album IDs", "tags": [ "Album" ], "operationId": "getAlbumIds", "description": "Resolve an album across platforms given a source identifier. `type` accepts `chartmetric`, `upc`, `spotify`, `itunes`, `deezer`, or `amazon`. Multiple rows per `cm_album` may be returned when an album has several platform identifiers.", "parameters": [ { "name": "type", "in": "path", "schema": { "type": "string", "enum": [ "chartmetric", "upc", "spotify", "itunes", "deezer", "amazon" ], "description": "Source identifier type. One of `chartmetric`, `upc`, `spotify`, `itunes`, `deezer`, or `amazon`." }, "required": true, "description": "Source identifier type. One of `chartmetric`, `upc`, `spotify`, `itunes`, `deezer`, or `amazon`.", "examples": { "default": { "value": "chartmetric" } } }, { "name": "id", "in": "path", "schema": { "type": "string", "pattern": "^[a-zA-Z0-9-_]+$", "description": "Album identifier whose format depends on `type` (numeric Chartmetric ID, UPC string, or platform-specific album ID)." }, "required": true, "description": "Album identifier whose format depends on `type` (numeric Chartmetric ID, UPC string, or platform-specific album ID).", "examples": { "default": { "value": "2762" } } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "array", "items": { "type": "object", "properties": { "cm_album": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric album ID." }, "album_name": { "type": [ "string", "null" ], "description": "Album name." }, "upc": { "type": [ "string", "null" ], "description": "Universal Product Code identifying the release." }, "spotify_album_id": { "type": [ "string", "null" ], "description": "Spotify album ID." }, "itunes_album_id": { "type": [ "string", "null" ], "description": "iTunes album ID." }, "deezer_album_id": { "type": [ "string", "null" ], "description": "Deezer album ID." }, "amazon_album_id": { "type": [ "string", "null" ], "description": "Amazon album ID (ASIN)." } }, "required": [ "cm_album" ] } } }, "required": [ "obj" ], "additionalProperties": false }, "examples": { "default": { "value": { "obj": [ { "cm_album": 815685, "album_name": "Deja Fu", "upc": "3614599568697", "spotify_album_id": "3hpphhVJM2QTUMYuXT7nw4", "itunes_album_id": "1126469777", "deezer_album_id": null, "amazon_album_id": "B01HDU9RN0" }, { "cm_album": 815685, "album_name": "Deja Fu", "upc": "3614599568697", "spotify_album_id": "3hpphhVJM2QTUMYuXT7nw4", "itunes_album_id": "1126469777", "deezer_album_id": null, "amazon_album_id": "B01HFW1FHW" } ] } } } } } } } } }, "/api/album/{id}": { "get": { "summary": "Album Metadata", "tags": [ "Album" ], "operationId": "getAlbumMetadata", "description": "Album metadata by Chartmetric ID.", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric album ID." }, "required": true, "description": "Chartmetric album ID.", "examples": { "default": { "value": 1 } } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Chartmetric album ID. Same value as `cm_album`." }, "upc": { "type": [ "string", "null" ], "description": "Universal Product Code identifying the release." }, "name": { "type": [ "string", "null" ], "description": "Album name." }, "local_name": { "type": [ "string", "null" ], "description": "Localized album name, when available." }, "local_name_locale": { "type": [ "string", "null" ], "description": "Locale for local_name, when available." }, "image_url": { "type": [ "string", "null" ], "description": "Album cover image URL." }, "release_date": { "type": [ "string", "null" ], "description": "Album release date (`YYYY-MM-DD`)." }, "label": { "type": [ "string", "null" ], "description": "Record label that released the album." }, "distributor": { "type": [ "string", "null" ], "description": "Distributor of the release, when known. `null` until the album has been looked up or when no distributor was found." }, "spotify_popularity": { "type": [ "integer", "null" ], "minimum": 0, "description": "Spotify popularity score (0–100) at the time of caching." }, "cm_label": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Chartmetric label ID." }, "description": { "type": [ "string", "null" ], "description": "Album description." }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Date the album row was created in Chartmetric." }, "modified_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Date the album row was last modified in Chartmetric." }, "cm_album": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric album ID." }, "num_track": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Number of tracks on the album." }, "spotify_album_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Spotify album IDs associated with this album." }, "itunes_album_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "iTunes album IDs associated with this album." }, "deezer_album_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Deezer album IDs associated with this album." }, "artists": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "cm_artist": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Chartmetric artist ID." }, "name": { "type": [ "string", "null" ], "description": "Artist name." }, "image_url": { "type": [ "string", "null" ], "description": "Artist image URL." } } }, "description": "Artists credited on the album." }, "cm_statistics": { "type": [ "object", "null" ], "properties": { "sp_popularity": { "type": [ "integer", "null" ], "minimum": 0, "description": "Spotify popularity score (0–100)." }, "num_sp_editorial_playlists": { "type": [ "integer", "null" ], "minimum": 0, "description": "Count of Spotify editorial playlists featuring this album." }, "num_sp_playlists": { "type": [ "integer", "null" ], "minimum": 0, "description": "Count of Spotify playlists featuring this album." }, "sp_playlist_total_reach": { "type": [ "integer", "null" ], "minimum": 0, "description": "Sum of followers across all Spotify playlists featuring this album." }, "sp_editorial_playlist_total_reach": { "type": [ "integer", "null" ], "minimum": 0, "description": "Sum of followers across all Spotify editorial playlists featuring this album." } }, "description": "Cached playlist statistics for the album." } }, "required": [ "cm_album" ] } }, "additionalProperties": false }, "examples": { "default": { "value": { "obj": { "id": null, "upc": "3614599568697", "name": "Deja Fu", "local_name": null, "local_name_locale": null, "image_url": "https://i.scdn.co/image/250c66bd1cfd8e1177055c998b43feac5a62ed0d", "release_date": "2016-06-22", "label": "Ranka Kustannus Oy", "distributor": null, "spotify_popularity": 2, "cm_label": 44035, "description": null, "created_at": null, "modified_at": null, "cm_album": 815685, "num_track": "1", "spotify_album_ids": [ "3hpphhVJM2QTUMYuXT7nw4" ], "itunes_album_ids": null, "deezer_album_ids": null, "artists": [ { "cm_artist": 256101, "name": "Blind Channel", "image_url": "https://i.scdn.co/image/99ff63e0299ffe1faa62d90056f6ca59aa2f3443" } ], "cm_statistics": { "sp_popularity": 2, "num_sp_editorial_playlists": 1, "num_sp_playlists": 19, "sp_playlist_total_reach": 10757, "sp_editorial_playlist_total_reach": 0 } } } } } } } } } } }, "/api/album/{id}/tracks": { "get": { "summary": "Album Tracks", "tags": [ "Album" ], "operationId": "listAlbumTracks", "description": "Tracks on an album identified by Chartmetric ID. Each track carries cross-platform IDs, artist arrays, and a `cm_statistics` aggregate. Prefer `cm_artists[].{id,name,code2,image_url,cover_url}` over the parallel `cm_artist`, `artist_names`, `code2s`, `artist_images`, `artist_covers` arrays — those are retained for compatibility.", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric album ID." }, "required": true, "description": "Chartmetric album ID.", "examples": { "default": { "value": 1 } } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric track ID." }, "name": { "type": [ "string", "null" ], "description": "Track name." }, "local_name": { "type": [ "string", "null" ], "description": "Localized track name, when available." }, "local_name_locale": { "type": [ "string", "null" ], "description": "Locale for local_name, when available." }, "image_url": { "type": [ "string", "null" ], "description": "Track cover image URL." }, "isrc": { "type": [ "string", "null" ], "description": "International Standard Recording Code for the track." }, "description": { "type": [ "string", "null" ], "description": "Track description." }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Date the track row was created in Chartmetric." }, "modified_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Date the track row was last modified in Chartmetric." }, "tags": { "type": [ "string", "null" ], "description": "Comma-separated list of genres for the track." }, "cm_track": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Chartmetric track ID." }, "cm_artist": { "type": [ "array", "null" ], "items": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "description": "Chartmetric artist IDs. Index aligns with `artist_names`, `code2s`, `artist_images`, `artist_covers`. Prefer `cm_artists[].id`." }, "artist_names": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Artist names. Deprecated; prefer `cm_artists[].name`." }, "code2s": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB')." }, "description": "Artist country codes (ISO 3166-1 alpha-2). Deprecated; prefer `cm_artists[].code2`." }, "artist_images": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Artist image URLs. Deprecated; prefer `cm_artists[].image_url`." }, "artist_covers": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Artist cover image URLs. Deprecated; prefer `cm_artists[].cover_url`." }, "spotify_track_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Spotify track IDs, sorted by popularity score." }, "spotify_album_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Spotify album IDs the track appears on." }, "spotify_duration_ms": { "type": [ "integer", "null" ], "minimum": 0, "description": "Track duration on Spotify in milliseconds." }, "itunes_track_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "iTunes track IDs." }, "itunes_album_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "iTunes album IDs the track appears on." }, "storefronts": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "ISO 3166-1 alpha-2 codes for iTunes storefronts where the track is available." }, "deezer_track_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Deezer track IDs." }, "deezer_album_ids": { "type": [ "array", "null" ], "items": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ] }, "description": "Deezer album IDs the track appears on." }, "deezer_duration": { "type": [ "integer", "null" ], "minimum": 0, "description": "Track duration on Deezer in seconds." }, "amazon_track_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Amazon track IDs." }, "amazon_album_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Amazon album IDs the track appears on." }, "album_ids": { "type": [ "array", "null" ], "items": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "description": "Chartmetric album IDs the track appears on. Index aligns with `album_names`, `album_upc`, `album_label`, `release_dates`." }, "album_names": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Album names." }, "album_upc": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Album UPC codes." }, "album_label": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Album record labels." }, "release_dates": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Album release dates." }, "cm_artists": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 2, "maximum": 2147483647, "not": { "enum": [ 1 ] }, "description": "Chartmetric artist ID. Note: id=1 ('Various Artists') is rejected." }, "name": { "type": [ "string", "null" ], "description": "Artist name." }, "code2": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2, "description": "Artist country code (ISO 3166-1 alpha-2, e.g. 'US')." }, "image_url": { "type": [ "string", "null" ], "description": "Artist image URL." }, "cover_url": { "type": [ "string", "null" ], "description": "Artist cover image URL." } }, "required": [ "id" ] }, "description": "Artists credited on the track." }, "cm_statistics": { "type": [ "object", "null" ], "properties": { "num_sp_editorial_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Count of Spotify editorial playlists featuring this track." }, "num_sp_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Count of Spotify playlists featuring this track." }, "sp_playlist_total_reach": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Sum of followers across all Spotify playlists featuring this track. Returned as a string when the value originates from Snowflake." }, "num_am_editorial_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Count of Apple Music editorial playlists featuring this track." }, "num_am_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Count of Apple Music playlists featuring this track." }, "num_de_editorial_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Count of Deezer editorial playlists featuring this track." }, "num_de_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Count of Deezer playlists featuring this track." }, "de_playlist_total_reach": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Sum of fans across all Deezer playlists featuring this track. Returned as a string when the value originates from Snowflake." }, "num_az_editorial_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Count of Amazon editorial playlists featuring this track." }, "num_az_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Count of Amazon playlists featuring this track." }, "num_yt_editorial_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Count of YouTube editorial playlists featuring this track." }, "num_yt_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Count of YouTube playlists featuring this track." }, "yt_playlist_total_reach": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Sum of subscribers across all YouTube playlists featuring this track. Returned as a string when the value originates from Snowflake." }, "cm_track": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Chartmetric track ID." }, "sp_popularity": { "type": [ "integer", "null" ], "minimum": 0, "description": "Spotify popularity score (0–100)." }, "num_tt_videos": { "type": [ "integer", "null" ], "minimum": 0, "description": "Count of TikTok videos using this track." }, "genius_page_views": { "type": [ "number", "null" ], "format": "float", "description": "Total Genius lyrics page views for the track." }, "shazam_counts": { "type": [ "number", "null" ], "format": "float", "description": "Total Shazam recognitions for the track." }, "tiktok_counts": { "type": [ "number", "null" ], "format": "float", "description": "Total TikTok plays for the track." }, "youtube_views": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Total YouTube views for the track. Returned as a string when the value originates from Snowflake." } }, "description": "Aggregated playlist counts and platform statistics for the track." } }, "required": [ "id" ] } } }, "required": [ "obj" ], "additionalProperties": false }, "examples": { "default": { "value": { "obj": [ { "id": 22396642, "name": "break up with your girlfriend, i'm bored", "image_url": "https://api.deezer.com/album/86773062/image", "isrc": "USUM71900409", "description": null, "created_at": null, "modified_at": "2020-07-03T05:46:13.804Z", "tags": "Pop,Music", "cm_track": 22396642, "cm_artist": [ 3963 ], "artist_names": [ "Ariana Grande" ], "code2s": [ "US" ], "artist_images": [ "https://i.scdn.co/image/b1dfbe843b0b9f54ab2e588f33e7637d2dab065a" ], "artist_covers": [ "https://i.scdn.co/image/4599ff6a6b96d54df41e97a484605f0e517ba278" ], "spotify_track_ids": [ "4kV4N9D1iKVxx1KLvtTpjS" ], "spotify_album_ids": [ "2fYhqwDWXjbpjaIJPEfKFw" ], "spotify_duration_ms": 190440, "itunes_track_ids": [ "1450330687" ], "itunes_album_ids": [ "1450330588" ], "storefronts": [ "LA" ], "deezer_track_ids": [ "629899862" ], "deezer_album_ids": [ 86773062 ], "deezer_duration": 190, "amazon_track_ids": [ "B082XHFBS6" ], "amazon_album_ids": [ "B082XGFGGN" ], "album_ids": [ 3533190 ], "album_names": [ "thank u, next" ], "album_upc": [ "602577464980" ], "album_label": [ "Republic Records" ], "release_dates": [ "2019-02-08T08:00:00.000Z" ], "cm_artists": [ { "id": 3963, "name": "Ariana Grande", "code2": "US", "image_url": "https://i.scdn.co/image/b1dfbe843b0b9f54ab2e588f33e7637d2dab065a", "cover_url": "https://i.scdn.co/image/4599ff6a6b96d54df41e97a484605f0e517ba278" } ], "cm_statistics": { "num_sp_playlists": 3556, "num_sp_editorial_playlists": 57, "num_am_playlists": 49, "num_am_editorial_playlists": 4, "num_de_playlists": 11, "num_de_editorial_playlists": 2, "num_az_playlists": 36, "num_az_editorial_playlists": 36, "num_yt_playlists": 12, "num_yt_editorial_playlists": 3, "sp_playlist_total_reach": "10760959", "de_playlist_total_reach": "350115", "yt_playlist_total_reach": "6404331", "cm_track": 22396642, "sp_popularity": 80, "num_tt_videos": 69100, "genius_page_views": null, "shazam_counts": 1896424, "tiktok_counts": 69100, "youtube_views": "369742364" } } ] } } } } } } } } }, "/api/album/{id}/{platform}/{stats}": { "get": { "summary": "Album Platform Stats", "tags": [ "Album" ], "operationId": "getAlbumStats", "description": "Time-series of a platform-specific stat for an album (currently `platform=spotify`, `stat=followers` returns Spotify popularity). Pass `latest=true` to bypass the date window and receive the most recent point.", "parameters": [ { "name": "platform", "in": "path", "schema": { "type": "string", "enum": [ "spotify" ], "description": "Streaming platform whose stat is requested. Currently only `spotify` is supported." }, "required": true, "description": "Streaming platform whose stat is requested. Currently only `spotify` is supported.", "examples": { "default": { "value": "spotify" } } }, { "name": "stats", "in": "path", "schema": { "type": "string", "enum": [ "followers" ], "description": "Platform stat to retrieve. Currently only `followers` is supported (returns Spotify popularity)." }, "required": true, "description": "Platform stat to retrieve. Currently only `followers` is supported (returns Spotify popularity).", "examples": { "default": { "value": "followers" } } }, { "name": "id", "in": "path", "schema": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric album ID." }, "required": true, "description": "Chartmetric album ID.", "examples": { "default": { "value": 1 } } }, { "name": "since", "in": "query", "schema": { "type": "string", "format": "date", "description": "Start of the date window in ISO format (e.g. '2025-11-01'). Defaults to 180 days ago.", "default": "2026-05-09" }, "required": false, "description": "Start of the date window in ISO format (e.g. '2025-11-01'). Defaults to 180 days ago." }, { "name": "until", "in": "query", "schema": { "type": "string", "format": "date", "description": "End of the date window in ISO format (e.g. '2025-11-15'). Defaults to today.", "default": "2026-11-05" }, "required": false, "description": "End of the date window in ISO format (e.g. '2025-11-15'). Defaults to today." }, { "name": "latest", "in": "query", "schema": { "type": "boolean", "description": "If true, returns only the most recent data point and ignores the `since`/`until` window." }, "required": false, "description": "If true, returns only the most recent data point and ignores the `since`/`until` window." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "number", "format": "float", "description": "Stat value at `timestp`. Despite the path slug `followers`, the value returned for `platform=spotify` is the Spotify album popularity (0–100), not a follower count." }, "timestp": { "type": "string", "format": "date-time", "description": "Timestamp the data point was recorded." }, "daily_diff": { "type": "number", "format": "float", "description": "Change in `value` versus the previous day." }, "weekly_diff": { "type": "number", "format": "float", "description": "Change in `value` versus 7 days prior." }, "monthly_diff": { "type": "number", "format": "float", "description": "Change in `value` versus 30 days prior." }, "weekly_diff_percent": { "type": "number", "format": "float", "description": "Percent change in `value` versus 7 days prior." }, "monthly_diff_percent": { "type": "number", "format": "float", "description": "Percent change in `value` versus 30 days prior." }, "flags": { "type": "boolean", "description": "True when this point carries data-quality flags." }, "interpolated": { "type": "boolean", "description": "True when the value was interpolated from neighboring points." }, "extrapolated": { "type": "boolean", "description": "True when the value was extrapolated beyond the source series." } }, "required": [ "value", "timestp" ] } } }, "required": [ "obj" ], "additionalProperties": false }, "examples": { "default": { "value": { "obj": [ { "value": 97, "timestp": "2020-09-20T07:00:00.000Z" }, { "value": 97, "timestp": "2020-09-21T07:00:00.000Z" }, { "value": 97, "timestp": "2020-09-22T07:00:00.000Z" }, { "value": 97, "timestp": "2020-09-23T07:00:00.000Z" } ] } } } } } } } } }, "/api/album/{id}/{platform}/{status}/playlists": { "get": { "summary": "Album Playlists", "tags": [ "Album" ], "operationId": "listAlbumPlaylists", "description": "Playlists (`status=current` or `past`) featuring an album on a given streaming platform. Items pair a `playlist` object with the corresponding `track` metadata.\n\n**Boolean flag parameters supported per platform:**\n\n| Flag | spotify | applemusic | deezer | amazon |\n|---|:---:|:---:|:---:|:---:|\n| `editorial` | ✅ | ✅ | ✅ | |\n| `editorialBrand` | | ✅ | | |\n| `personalized` | ✅ | | | |\n| `deezerPartner` | | | ✅ | |\n| `chart` | ✅ | ✅ | ✅ | |\n| `thisIs` | ✅ | | | |\n| `hundredPercent` | | | ✅ | |\n| `newMusicFriday` | ✅ | | | |\n| `radio` | ✅ | ✅ | | |\n| `fullyPersonalized` | ✅ | | | |\n| `brand` | ✅ | | ✅ | |\n| `majorCurator` | ✅ | | ✅ | |\n| `musicBrand` | | ✅ | | |\n| `nonMusicBrand` | | ✅ | | |\n| `popularIndie` | ✅ | | ✅ | |\n| `indie` | ✅ | ✅ | ✅ | |\n| `audiobook` | ✅ | | | |\n| `personalityArtist` | | ✅ | | |\n\nAmazon does not accept any flags. Flags are not mutually exclusive — pass others as `false` to scope to one. When no flags are specified the API may return an empty array; specify flags explicitly to get data.", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric album ID." }, "required": true, "description": "Chartmetric album ID.", "examples": { "default": { "value": 1 } } }, { "name": "platform", "in": "path", "schema": { "type": "string", "enum": [ "cm", "spotify", "itunes", "applemusic", "deezer", "shazam", "beatport", "amazon", "youtube", "tunefind", "soundcloud" ], "description": "Streaming platform. One of `spotify`, `applemusic`, `deezer`, or `amazon`; supported boolean filters vary by platform." }, "required": true, "description": "Streaming platform. One of `spotify`, `applemusic`, `deezer`, or `amazon`; supported boolean filters vary by platform.", "examples": { "default": { "value": "cm" } } }, { "name": "status", "in": "path", "schema": { "type": "string", "enum": [ "current", "past" ], "description": "Playlist status relative to the album. `current` returns playlists currently containing a track from the album; `past` returns playlists that previously contained one." }, "required": true, "description": "Playlist status relative to the album. `current` returns playlists currently containing a track from the album; `past` returns playlists that previously contained one.", "examples": { "default": { "value": "current" } } }, { "name": "since", "in": "query", "schema": { "type": "string", "format": "date", "description": "Start of the added/removed date window in ISO format (e.g. '2025-11-01'). Defaults to 180 days ago.", "default": "2026-05-09" }, "required": false, "description": "Start of the added/removed date window in ISO format (e.g. '2025-11-01'). Defaults to 180 days ago." }, { "name": "until", "in": "query", "schema": { "type": "string", "format": "date", "description": "End of the added/removed date window in ISO format (e.g. '2025-11-15'). Defaults to today.", "default": "2026-11-05" }, "required": false, "description": "End of the added/removed date window in ISO format (e.g. '2025-11-15'). Defaults to today." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, "required": false, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum number of items to return per request.", "default": 10 }, "required": false, "description": "Maximum number of items to return per request." }, { "name": "indie", "in": "query", "schema": { "type": "boolean", "description": "Filter to only playlists tagged as indie (independently curated)." }, "required": false, "description": "Filter to only playlists tagged as indie (independently curated)." }, { "name": "majorCurator", "in": "query", "schema": { "type": "boolean", "description": "Filter to only playlists owned by a major-label curator (Sony, Universal, Warner, etc.)." }, "required": false, "description": "Filter to only playlists owned by a major-label curator (Sony, Universal, Warner, etc.)." }, { "name": "editorial", "in": "query", "schema": { "type": "boolean", "description": "Filter to only editorial playlists curated by the platform (e.g. Spotify-owned). Defaults to true; pass `false` to include user-curated playlists.", "default": true }, "required": false, "description": "Filter to only editorial playlists curated by the platform (e.g. Spotify-owned). Defaults to true; pass `false` to include user-curated playlists." }, { "name": "newMusicFriday", "in": "query", "schema": { "type": "boolean", "description": "Filter to only New Music Friday-style new-release playlists." }, "required": false, "description": "Filter to only New Music Friday-style new-release playlists." }, { "name": "editorialBrand", "in": "query", "schema": { "type": "boolean", "description": "Filter to only editorial playlists operated by a brand (e.g. retailer or media outlet)." }, "required": false, "description": "Filter to only editorial playlists operated by a brand (e.g. retailer or media outlet)." }, { "name": "personalized", "in": "query", "schema": { "type": "boolean", "description": "Filter to only personalized playlists (e.g. Discover Weekly, Release Radar). May vary per listener." }, "required": false, "description": "Filter to only personalized playlists (e.g. Discover Weekly, Release Radar). May vary per listener." }, { "name": "deezerPartner", "in": "query", "schema": { "type": "boolean", "description": "Filter to only Deezer partner-curated playlists." }, "required": false, "description": "Filter to only Deezer partner-curated playlists." }, { "name": "chart", "in": "query", "schema": { "type": "boolean", "description": "Filter to only chart playlists (e.g. Top 50, Viral 50). Reflects platform-published rankings." }, "required": false, "description": "Filter to only chart playlists (e.g. Top 50, Viral 50). Reflects platform-published rankings." }, { "name": "thisIs", "in": "query", "schema": { "type": "boolean", "description": "Filter to only artist-spotlight playlists in the 'This Is X' format." }, "required": false, "description": "Filter to only artist-spotlight playlists in the 'This Is X' format." }, { "name": "hundredPercent", "in": "query", "schema": { "type": "boolean", "description": "Filter to only playlists composed entirely of one artist's catalog." }, "required": false, "description": "Filter to only playlists composed entirely of one artist's catalog." }, { "name": "radio", "in": "query", "schema": { "type": "boolean", "description": "Filter to only algorithmic radio-style playlists generated from a seed track or artist." }, "required": false, "description": "Filter to only algorithmic radio-style playlists generated from a seed track or artist." }, { "name": "fullyPersonalized", "in": "query", "schema": { "type": "boolean", "description": "Filter to only fully personalized playlists where the entire tracklist is unique per listener." }, "required": false, "description": "Filter to only fully personalized playlists where the entire tracklist is unique per listener." }, { "name": "brand", "in": "query", "schema": { "type": "boolean", "description": "Filter to only brand-operated playlists (any flavor — music, non-music, retailer, media)." }, "required": false, "description": "Filter to only brand-operated playlists (any flavor — music, non-music, retailer, media)." }, { "name": "musicBrand", "in": "query", "schema": { "type": "boolean", "description": "Filter to only music-industry brand playlists (labels, music publications)." }, "required": false, "description": "Filter to only music-industry brand playlists (labels, music publications)." }, { "name": "nonMusicBrand", "in": "query", "schema": { "type": "boolean", "description": "Filter to only non-music-industry brand playlists (retailers, media outlets, lifestyle)." }, "required": false, "description": "Filter to only non-music-industry brand playlists (retailers, media outlets, lifestyle)." }, { "name": "popularIndie", "in": "query", "schema": { "type": "boolean", "description": "Filter to only popular indie playlists with significant follower count." }, "required": false, "description": "Filter to only popular indie playlists with significant follower count." }, { "name": "audiobook", "in": "query", "schema": { "type": "boolean", "description": "Filter to only audiobook playlists." }, "required": false, "description": "Filter to only audiobook playlists." }, { "name": "personalityArtist", "in": "query", "schema": { "type": "boolean", "description": "Filter to only playlists curated by personality artists (artists with cultural influence beyond their music)." }, "required": false, "description": "Filter to only playlists curated by personality artists (artists with cultural influence beyond their music)." }, { "name": "minFollowers", "in": "query", "schema": { "type": "integer", "description": "Minimum follower count for returned playlists. Defaults to 0 (no minimum)." }, "required": false, "description": "Minimum follower count for returned playlists. Defaults to 0 (no minimum)." }, { "name": "showPositionStats", "in": "query", "schema": { "type": "boolean", "description": "If true, include track position statistics on each playlist entry.", "default": false }, "required": false, "description": "If true, include track position statistics on each playlist entry." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "array", "items": { "type": "object", "properties": { "playlist": { "type": "object", "properties": { "playlist_id": { "type": [ "string", "null" ], "description": "Platform playlist ID (e.g. Spotify playlist ID extracted from the URI)." }, "track_id": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Chartmetric track ID of the album track on this playlist." }, "position": { "type": [ "integer", "null" ], "minimum": 0, "description": "Track position within the playlist (1-based)." }, "added_at": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Date the track was added to the playlist." }, "period": { "type": [ "integer", "null" ], "minimum": 0, "description": "Number of days the track has been on the playlist." }, "id": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Internal playlist row ID; deprecated, prefer `playlist_id`." }, "name": { "type": [ "string", "null" ], "description": "Playlist title." }, "description": { "type": [ "string", "null" ], "description": "Playlist description as set by the curator." }, "image_url": { "type": [ "string", "null" ], "description": "Playlist cover image URL." }, "sys_last_updated": { "type": [ "string", "null" ], "format": "date-time", "description": "Date Chartmetric last refreshed this playlist record." }, "last_updated": { "type": [ "string", "null" ], "format": "date-time", "description": "Date the playlist was last updated by its curator on the source platform." }, "personalized": { "type": [ "boolean", "null" ], "description": "True when the playlist is personalized to individual users by the platform." }, "code2": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2, "description": "Country associated with the playlist (ISO 3166-1 alpha-2)." }, "owner_name": { "type": [ "string", "null" ], "description": "Curator (playlist owner) display name." }, "owner_id": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Curator (playlist owner) ID — internal value, format varies by platform." }, "editorial": { "type": [ "boolean", "null" ], "description": "True when the playlist is curated by an official editorial team. Applies to Spotify, Apple Music, and Deezer." }, "tags": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric tag ID." }, "name": { "type": [ "string", "null" ], "description": "Tag name." } }, "required": [ "id" ] }, "description": "Genre / mood tags associated with the playlist." }, "followers": { "type": [ "integer", "null" ], "minimum": 0, "description": "Most recent follower count for the playlist." }, "num_track": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Total number of tracks on the playlist." }, "fdiff_week": { "type": [ "integer", "null" ], "description": "Follower change versus 7 days prior (weekly growth)." }, "fdiff_month": { "type": [ "integer", "null" ], "description": "Follower change versus 30 days prior (monthly growth)." }, "catalog": { "type": [ "string", "null" ], "description": "Catalog classification of the playlist." }, "active_ratio": { "type": [ "number", "null" ], "format": "float", "description": "Fraction (0–1) of recent days the playlist has been active." } }, "description": "Playlist that hosted the album track during the requested period." }, "track": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Internal track row ID; deprecated, prefer `cm_track`." }, "name": { "type": [ "string", "null" ], "description": "Track name." }, "isrc": { "type": [ "string", "null" ], "description": "International Standard Recording Code for the track." }, "spotify_album_id": { "type": [ "string", "null" ], "description": "Spotify album ID the track was sourced from." }, "image_url": { "type": [ "string", "null" ], "description": "Track cover image URL." }, "spotify_popularity": { "type": [ "integer", "null" ], "minimum": 0, "description": "Spotify popularity score (0–100) for the track." }, "cm_track": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Chartmetric track ID." }, "spotify_artist_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Artist names as listed on Spotify." }, "track_genre": { "type": [ "string", "null" ], "description": "Comma-separated genre list for the track." }, "cm_artist": { "type": [ "array", "null" ], "items": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "description": "Chartmetric artist IDs. Index aligns with `artist_names`, `code2s`, `artist_images`, `artist_covers`." }, "artist_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Artist names." }, "code2s": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB')." }, "description": "Artist country codes (ISO 3166-1 alpha-2)." }, "artist_images": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Artist image URLs." }, "artist_covers": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Artist cover image URLs." }, "spotify_artist_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Spotify artist IDs." }, "spotify_track_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Spotify track IDs." }, "spotify_album_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Spotify album IDs the track appears on." }, "spotify_duration_ms": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "array", "items": {} } ], "nullable": true, "description": "Track duration on Spotify in milliseconds. May arrive as an array of values when multiple Spotify track IDs map to the same Chartmetric track." }, "album_ids": { "type": [ "array", "null" ], "items": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "description": "Chartmetric album IDs the track appears on. Index aligns with `album_names`, `album_upc`, `album_label`, `release_dates`." }, "album_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Album names." }, "album_upc": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Album UPC codes." }, "album_label": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Album record labels." }, "release_dates": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Album release dates." } }, "description": "Album track that appears on the playlist (cross-platform metadata)." } } } } }, "required": [ "obj" ], "additionalProperties": false }, "examples": { "default": { "value": { "obj": [ { "playlist": { "playlist_id": "37i9dQZF1DWWMOmoXKqHTD", "track_id": 17340502, "position": 22, "added_at": "2023-07-11", "period": 105, "id": 1644599, "name": "Songs to Sing in the Car", "description": "", "image_url": "https://i.scdn.co/image/ab67706f00000003ffa215be1a4c64e3cbf59d1e", "sys_last_updated": "2023-10-24T00:00:00.000Z", "last_updated": "2023-10-21T09:09:20.000Z", "personalized": true, "code2": "US", "owner_name": "Spotify", "owner_id": 2, "editorial": false, "tags": [ { "id": 462882, "name": "Pop" }, { "id": 462884, "name": "Rock" }, { "id": 462889, "name": "R&B/Soul" } ], "followers": 10707440, "num_track": 100, "fdiff_week": 11408, "fdiff_month": 36241, "catalog": "catalogue ", "active_ratio": 0 }, "track": { "id": 17340502, "name": "Watermelon Sugar", "isrc": "USSM11912587", "spotify_album_id": "7xV2TzoaVc0ycW7fwBwAml", "image_url": "https://api.deezer.com/album/119400582/image", "spotify_popularity": 89, "cm_track": 27222889, "spotify_artist_names": [ "Harry Styles" ], "track_genre": "dance pop,pop,post-teen pop", "cm_artist": [ 558681 ], "artist_names": [ "Harry Styles" ], "code2s": [ "GB" ], "artist_images": [ "https://i.scdn.co/image/ab67616100005174f7db7c8ede90a019c54590bb" ], "artist_covers": [ null ], "spotify_artist_ids": [ "6KImCVD70vtIoJWnq6nGn3" ], "spotify_track_ids": [ "6UelLqGlWMcVH1E5c4H7lY" ], "spotify_album_ids": [ "7xV2TzoaVc0ycW7fwBwAml" ], "spotify_duration_ms": 174000, "album_ids": [ 5370467 ], "album_names": [ "Watermelon Sugar" ], "album_upc": [ "886448132844" ], "album_label": [ "Columbia" ], "release_dates": [ "2019-12-13" ] } } ] } } } } } } } } }, "/api/artist/anr/by/playlists": { "get": { "summary": "A&R Artists by Playlists", "tags": [ "Artist" ], "operationId": "listArtistsByPlaylistsANR", "description": "A&R-oriented artist snapshot sorted by Spotify playlist-count growth. Hydrated from the `cm_artist_cache` ES index; per-artist releases come from the earliest/latest album query.", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "maximum": 100, "description": "Maximum number of artists to return. Defaults to 10, max 100.", "default": 10 }, "required": false, "description": "Maximum number of artists to return. Defaults to 10, max 100." }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "enum": [ "followers_total_reach_diff_week_percent", "followers_total_reach_diff_week" ], "description": "Column to sort by. One of `followers_total_reach_diff_week_percent`, `followers_total_reach_diff_week`." }, "required": true, "description": "Column to sort by. One of `followers_total_reach_diff_week_percent`, `followers_total_reach_diff_week`.", "examples": { "default": { "value": "followers_total_reach_diff_week_percent" } } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "array", "items": { "type": "object", "properties": { "rank": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "nullable": true, "description": "1-based position of the artist within the sorted result set." }, "id": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Chartmetric artist ID." }, "name": { "type": [ "string", "null" ], "description": "Artist name." }, "image_url": { "type": [ "string", "null" ], "description": "Artist image URL." }, "code2": { "type": [ "string", "null" ], "description": "Artist country (ISO 3166-1 alpha-2)." }, "sp_followers": { "type": [ "integer", "null" ], "minimum": 0, "description": "Spotify follower count." }, "sp_popularity": { "type": [ "integer", "null" ], "description": "Spotify popularity score (0–100)." }, "sp_monthly_listeners": { "type": [ "integer", "null" ], "minimum": 0, "description": "Spotify monthly listener count." }, "deezer_fans": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Deezer fan count. May arrive as string (uncast aggregate)." }, "tags": { "type": [ "array", "null" ], "items": {}, "description": "List of artist genre tags." }, "spotify_artist_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Spotify artist IDs linked to this Chartmetric artist." }, "cm_artist_rank": { "type": [ "integer", "null" ], "description": "Chartmetric overall artist rank." }, "cm_artist_score": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric artist score (0–100)." }, "num_tracks": { "type": [ "integer", "null" ], "description": "Number of tracks featured in playlists for this artist." }, "num_playlists": { "type": [ "integer", "null" ], "description": "Number of playlists featuring this artist." }, "num_playlists_diff_week": { "type": [ "integer", "null" ], "description": "Weekly change in playlist count (vs 7 days ago)." }, "num_playlists_diff_week_percent": { "type": [ "number", "null" ], "format": "float", "description": "Weekly percentage change in playlist count." }, "followers_total_reach": { "type": [ "integer", "null" ], "minimum": 0, "description": "Sum of follower counts across all playlists featuring this artist." }, "followers_total_reach_diff_week": { "type": [ "integer", "null" ], "description": "Weekly change in total playlist follower reach." }, "followers_total_reach_diff_week_percent": { "type": [ "number", "null" ], "format": "float", "description": "Weekly percentage change in total playlist follower reach." }, "popularity": { "type": [ "integer", "null" ], "description": "Spotify popularity score (0–100, higher is more popular)." }, "popularity_diff_week": { "type": [ "integer", "null" ], "description": "Weekly change in Spotify popularity." }, "popularity_diff_week_percent": { "type": [ "number", "null" ], "format": "float", "description": "Weekly percentage change in Spotify popularity." }, "followers": { "type": [ "integer", "null" ], "minimum": 0, "description": "Spotify follower count." }, "followers_diff_week": { "type": [ "integer", "null" ], "description": "Weekly change in Spotify follower count." }, "followers_diff_week_percent": { "type": [ "number", "null" ], "format": "float", "description": "Weekly percentage change in Spotify follower count." }, "listeners": { "type": [ "integer", "null" ], "minimum": 0, "description": "Spotify monthly listener count." }, "listeners_diff_week": { "type": [ "integer", "null" ], "description": "Weekly change in Spotify monthly listeners." }, "listeners_diff_week_percent": { "type": [ "number", "null" ], "format": "float", "description": "Weekly percentage change in Spotify monthly listeners." }, "timestp": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Timestamp for the snapshot (ISO 8601)." }, "releases": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "cm_album": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Chartmetric album ID." }, "album_name": { "type": [ "string", "null" ], "description": "Album name." }, "release_date": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Album release date (ISO 8601)." }, "upc": { "type": [ "string", "null" ], "description": "Universal Product Code identifying the release." }, "label": { "type": [ "string", "null" ], "description": "Record label that released the album." }, "image_url": { "type": [ "string", "null" ], "description": "Album cover image URL." } } }, "description": "List of the artist's earliest and latest album releases." }, "genres": { "type": [ "array", "null" ], "items": {}, "description": "List of genres for the artist." }, "authenticity_risk": { "description": "Authenticity-risk signals for the artist (shape varies)." } } } } }, "required": [ "obj" ], "additionalProperties": false }, "examples": { "default": { "value": { "obj": [ { "rank": 1, "id": 53722, "num_playlists": 17, "num_tracks": 1, "followers_total_reach": 1596657, "followers_total_reach_diff_week": 236916, "followers_total_reach_diff_week_percent": 0.1742, "popularity": 43, "popularity_diff_week": 0, "popularity_diff_week_percent": 0, "followers": 2570, "followers_diff_week": 2, "followers_diff_week_percent": 0.0008, "listeners": 182354, "listeners_diff_week": 1829, "listeners_diff_week_percent": 0.0101, "timestp": "2020-02-05T08:00:00.000Z", "name": "Tharyk", "image_url": "https://i.scdn.co/image/481216e68d8cdc2dad2ba9c64e4d9fcc98b5192a", "code2": null, "sp_followers": 2570, "sp_popularity": 43, "sp_monthly_listeners": 182354, "deezer_fans": 173, "tags": null, "spotify_artist_ids": [ "0l4NszHlXslt1dBt4Y28f7" ], "cm_artist_rank": 31792, "cm_artist_score": 54.2, "releases": [ { "cm_album": 469946, "album_name": "Mi Destino", "release_date": "2015-12-04T08:00:00.000Z", "upc": "859716151359", "label": "G+T Music", "image_url": "https://i.scdn.co/image/b08d575f8af8f5b3ccff6250103f878163be7cf7" } ], "genres": [] } ] } } } } } } } } }, "/api/artist/{id}/riaa": { "get": { "summary": "RIAA Certifications for Artist Albums", "tags": [ "Artist" ], "operationId": "getArtistRiaaCertifications", "description": "RIAA award certifications for albums on which this artist appears. `format` is lower-cased in the query (matches Chartmetric FE preference). Albums are resolved via `l_cm_album_cm_artist` → UPC join → `riaa_album_award`. Results are sorted by `certification_date` descending.", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer", "minimum": 2, "maximum": 2147483647, "not": { "enum": [ 1 ] }, "description": "Chartmetric artist ID. Note: id=1 ('Various Artists') is rejected." }, "required": true, "description": "Chartmetric artist ID. Note: id=1 ('Various Artists') is rejected.", "examples": { "default": { "value": 2 } } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "object", "properties": { "riaa_awards": { "type": "array", "items": { "type": "object", "properties": { "award_id": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Chartmetric RIAA award row ID." }, "cm_album": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Chartmetric album ID." }, "upc": { "type": [ "string", "null" ], "description": "Universal Product Code identifying the album release." }, "certification_date": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Date the award was certified (`YYYY-MM-DDT00:00:00.000Z`)." }, "award": { "type": [ "string", "null" ], "description": "Award tier (e.g. `Gold`, `1x Platinum`, `4x Multi-Platinum`)." }, "album_title": { "type": [ "string", "null" ], "description": "Album title." }, "format": { "type": [ "string", "null" ], "description": "Album format (e.g. `single`, `album`, `video single`). Lower-cased." }, "image_url": { "type": [ "string", "null" ], "description": "Album cover image URL." }, "label": { "type": [ "string", "null" ], "description": "Record label that released the album." } } }, "description": "List of RIAA award rows for albums on which this artist appears." } }, "required": [ "riaa_awards" ] } }, "additionalProperties": false }, "examples": { "default": { "value": { "obj": { "riaa_awards": [ { "cm_album": 9384, "upc": "602557276077", "certification_date": "2018-06-29T00:00:00.000Z", "award": "1x Platinum", "album_title": "Fake Love", "format": "single", "image_url": "https://i.scdn.co/image/...", "label": "Cash Money Records/Motown Records" }, { "cm_album": 9384, "upc": "602557276077", "certification_date": "2018-03-08T00:00:00.000Z", "award": "4x Multi-Platinum", "album_title": "Fake Love", "format": "single", "image_url": "https://i.scdn.co/image/...", "label": "Cash Money Records/Motown Records" } ] } } } } } } } } } }, "/api/artist/anr/by/social-index": { "get": { "summary": "A&R Artists by Social Index", "tags": [ "Artist" ], "operationId": "listArtistsBySocialIndexANR", "description": "A&R-oriented artist snapshot sorted by social / streaming growth metric. `sortBy` selects which service-type fields are hydrated and returned alongside `weekInsights` (7-day), `insights` (30-day), and `twoMonthInsights` (60-day) growth objects. External API forces `interval=monthly`.", "parameters": [ { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Number of items to skip from the start of the result set; capped so `limit + offset` does not exceed 10,000 (Elasticsearch max window)." }, "required": false, "description": "Number of items to skip from the start of the result set; capped so `limit + offset` does not exceed 10,000 (Elasticsearch max window)." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 0, "description": "Maximum number of artists to return. Defaults to 10, max 100.", "default": 10 }, "required": false, "description": "Maximum number of artists to return. Defaults to 10, max 100." }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "enum": [ "spotify_popularity", "spotify_followers", "spotify_monthly_listeners", "facebook_likes", "twitter_followers", "instagram_followers", "tiktok_followers", "wiki_views", "soundcloud_followers", "youtube_channel_views" ], "description": "Metric to sort by. One of `spotify_popularity`, `spotify_followers`, `spotify_monthly_listeners`, `facebook_likes`, `twitter_followers`, `instagram_followers`, `tiktok_followers`, `wiki_views`, `soundcloud_followers`, `youtube_channel_views`. `facebook_likes` is internally remapped to `fs_likes`." }, "required": true, "description": "Metric to sort by. One of `spotify_popularity`, `spotify_followers`, `spotify_monthly_listeners`, `facebook_likes`, `twitter_followers`, `instagram_followers`, `tiktok_followers`, `wiki_views`, `soundcloud_followers`, `youtube_channel_views`. `facebook_likes` is internally remapped to `fs_likes`.", "examples": { "default": { "value": "spotify_popularity" } } }, { "name": "tagIds", "in": "query", "schema": { "type": "integer", "description": "Optional parent genre ID to restrict the result set." }, "required": false, "description": "Optional parent genre ID to restrict the result set." }, { "name": "subTagIds", "in": "query", "schema": { "type": "integer", "description": "Optional child genre ID. Deprecated and has no effect on the model — kept for backwards compatibility." }, "required": false, "description": "Optional child genre ID. Deprecated and has no effect on the model — kept for backwards compatibility." }, { "name": "code2", "in": "query", "schema": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB')." }, "required": false, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB')." }, { "name": "sortOrderDesc", "in": "query", "schema": { "type": "boolean", "description": "If true (default), sort descending by `sortBy`.", "default": true }, "required": false, "description": "If true (default), sort descending by `sortBy`." }, { "name": "minThirtyDayGrowth", "in": "query", "schema": { "type": "integer", "description": "Minimum 30-day growth threshold for `sortBy`." }, "required": false, "description": "Minimum 30-day growth threshold for `sortBy`." }, { "name": "maxThirtyDayGrowth", "in": "query", "schema": { "type": "integer", "description": "Maximum 30-day growth threshold for `sortBy`." }, "required": false, "description": "Maximum 30-day growth threshold for `sortBy`." }, { "name": "minSpotifyFollowers", "in": "query", "schema": { "type": "integer", "description": "Minimum Spotify followers filter. Defaults to -1 (no minimum).", "default": -1 }, "required": false, "description": "Minimum Spotify followers filter. Defaults to -1 (no minimum)." }, { "name": "maxSpotifyFollowers", "in": "query", "schema": { "type": "integer", "description": "Maximum Spotify followers filter. Defaults to -1 (no maximum).", "default": -1 }, "required": false, "description": "Maximum Spotify followers filter. Defaults to -1 (no maximum)." }, { "name": "recentReleaseWithin", "in": "query", "schema": { "type": "integer", "description": "Restrict to artists whose first release is within this many days of today. Defaults to 2555 (~7 years).", "default": 2555 }, "required": false, "description": "Restrict to artists whose first release is within this many days of today. Defaults to 2555 (~7 years)." }, { "name": "latestReleaseWithin", "in": "query", "schema": { "type": "integer", "description": "Restrict to artists whose latest release is within this many days of today. Defaults to 60.", "default": 60 }, "required": false, "description": "Restrict to artists whose latest release is within this many days of today. Defaults to 60." }, { "name": "unsigned", "in": "query", "schema": { "type": "boolean", "description": "If true (default), restrict the result set to unsigned artists.", "default": true }, "required": false, "description": "If true (default), restrict the result set to unsigned artists." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "array", "items": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 2147483647 }, { "type": "string" } ], "nullable": true, "description": "Chartmetric artist ID. May arrive as string from ES." }, "name": { "type": [ "string", "null" ], "description": "Artist name." }, "code2": { "type": [ "string", "null" ], "description": "Artist country (ISO 3166-1 alpha-2)." }, "image_url": { "type": [ "string", "null" ], "description": "Artist image URL." }, "tags": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "List of artist genre tags." }, "spotify_artist_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Spotify artist IDs linked to this Chartmetric artist." }, "releases": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "cm_album": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Chartmetric album ID." }, "album_name": { "type": [ "string", "null" ], "description": "Album name." }, "release_date": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Album release date (ISO 8601)." }, "upc": { "type": [ "string", "null" ], "description": "Universal Product Code identifying the release." }, "label": { "type": [ "string", "null" ], "description": "Record label that released the album." }, "image_url": { "type": [ "string", "null" ], "description": "Album cover image URL." } } }, "description": "List of the artist's recent album releases." }, "insights": { "type": [ "object", "null" ], "properties": { "fdiff": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Absolute follower-difference over the window (period-end minus period-start)." }, "fdiff_percent": { "type": [ "number", "null" ], "format": "float", "description": "Percentage follower-difference over the window." }, "sns": { "type": [ "string", "null" ], "description": "Social/streaming metric key the diff applies to (e.g. `spotify_m`, `instagram_f`)." }, "value": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Latest absolute value of the metric at the end of the window." } }, "description": "30-day growth insight." }, "weekInsights": { "type": [ "object", "null" ], "properties": { "fdiff": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Absolute follower-difference over the window (period-end minus period-start)." }, "fdiff_percent": { "type": [ "number", "null" ], "format": "float", "description": "Percentage follower-difference over the window." }, "sns": { "type": [ "string", "null" ], "description": "Social/streaming metric key the diff applies to (e.g. `spotify_m`, `instagram_f`)." }, "value": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Latest absolute value of the metric at the end of the window." } }, "description": "7-day growth insight." }, "twoMonthInsights": { "type": [ "object", "null" ], "properties": { "fdiff": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Absolute follower-difference over the window (period-end minus period-start)." }, "fdiff_percent": { "type": [ "number", "null" ], "format": "float", "description": "Percentage follower-difference over the window." }, "sns": { "type": [ "string", "null" ], "description": "Social/streaming metric key the diff applies to (e.g. `spotify_m`, `instagram_f`)." }, "value": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Latest absolute value of the metric at the end of the window." } }, "description": "60-day growth insight." }, "sp_followers": { "type": [ "integer", "null" ], "minimum": 0, "description": "Latest Spotify follower count." }, "signed": { "type": [ "boolean", "null" ], "description": "Whether the artist is currently signed to a record label." } } } } }, "required": [ "obj" ], "additionalProperties": false }, "examples": { "default": { "value": { "obj": [ { "name": "jnhygs", "code2": null, "image_url": "https://i.scdn.co/image/ab67616100005174e370de7eb3169eeeb57bf5d1", "tags": [ "Hip-Hop/Rap", "Pop", "Electronic" ], "spotify_artist_ids": [ "0H942IkjXv9bjx5OxoG7kh" ], "id": "9995920", "releases": [ { "cm_album": 26281529, "album_name": "XTAYALIVE", "release_date": "2023-02-19T00:00:00.000Z", "label": "4990469 Records DK", "image_url": "https://i.scdn.co/image/ab67616d0000b2734b1357973723dcf2e1a9cbe0", "upc": "197631029842" } ], "weekInsights": { "fdiff": 388076, "fdiff_percent": 21.7568, "sns": "spotify_m", "value": 2171776 }, "insights": { "fdiff": 1896287, "fdiff_percent": 688.3349, "sns": "spotify_m", "value": 2171776 }, "twoMonthInsights": { "fdiff": null, "fdiff_percent": null, "sns": "spotify_m", "value": 2171776 }, "sp_followers": 13371, "signed": false } ] } } } } } } } } }, "/api/artist/{id}/cpp": { "get": { "summary": "Cross-Platform Performance (CPP)", "tags": [ "Artist" ], "operationId": "getArtistCppScore", "description": "Cross-Platform Performance rank or score time-series for the artist. `stat=score` returns `{ score, timestp }` rows, `stat=rank` returns `{ rank, timestp }`; when `stat=rank` is combined with `latest=true`, the response additionally carries `rank_25_75`. Values come from Snowflake and keys are lower-cased in the API layer.", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer", "minimum": 2, "maximum": 2147483647, "not": { "enum": [ 1 ] }, "description": "Chartmetric artist ID. Note: id=1 ('Various Artists') is rejected." }, "required": true, "description": "Chartmetric artist ID. Note: id=1 ('Various Artists') is rejected.", "examples": { "default": { "value": 2 } } }, { "name": "since", "in": "query", "schema": { "type": "string", "format": "date", "description": "Start of the date range in ISO format (e.g. '2025-11-01'). Defaults to 20 days ago. Ignored when `latest=true`.", "default": "2026-10-16" }, "required": false, "description": "Start of the date range in ISO format (e.g. '2025-11-01'). Defaults to 20 days ago. Ignored when `latest=true`." }, { "name": "until", "in": "query", "schema": { "type": "string", "format": "date", "description": "End of the date range in ISO format (e.g. '2025-11-01'). Defaults to today. Ignored when `latest=true`.", "default": "2026-11-05" }, "required": false, "description": "End of the date range in ISO format (e.g. '2025-11-01'). Defaults to today. Ignored when `latest=true`." }, { "name": "stat", "in": "query", "schema": { "type": "string", "enum": [ "score", "rank" ], "description": "CPP statistic to return. `rank` is the Chartmetric Cross-Platform Performance rank; `score` is the underlying 0–1 score from which the rank is derived." }, "required": true, "description": "CPP statistic to return. `rank` is the Chartmetric Cross-Platform Performance rank; `score` is the underlying 0–1 score from which the rank is derived.", "examples": { "default": { "value": "score" } } }, { "name": "latest", "in": "query", "schema": { "type": "boolean", "description": "If true, returns only the most recent data point and ignores `since`/`until`." }, "required": false, "description": "If true, returns only the most recent data point and ignores `since`/`until`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "array", "items": { "type": "object", "properties": { "score": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric Cross-Platform Performance score (0–1). Present when `stat=score`." }, "rank": { "type": [ "integer", "null" ], "description": "Chartmetric Cross-Platform Performance rank. Present when `stat=rank`." }, "rank_25_75": { "type": [ "number", "null" ], "format": "float", "description": "Deprecated rank field; emitted only when `stat=rank` and `latest=true`. Use `rank` instead." }, "timestp": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Date the statistic was achieved (ISO 8601)." } } } } }, "required": [ "obj" ], "additionalProperties": false }, "examples": { "default": { "value": { "obj": [ { "score": 0.777289463353648, "timestp": "2019-12-10T00:00:00.000Z" }, { "score": 0.812443293506014, "timestp": "2019-12-12T00:00:00.000Z" }, { "score": 0.758845785647956, "timestp": "2019-12-13T00:00:00.000Z" } ] } } } } } } } } }, "/api/artist/{id}/{type}/charts": { "get": { "summary": "List Chart Appearances for an Artist", "tags": [ "Artist" ], "operationId": "listArtistCharts", "description": "Chart records for an artist across the supported platforms: Amazon, Spotify (`spotify_viral_daily`, `spotify_viral_weekly`, `spotify_top_daily`, `spotify_top_weekly`), Apple Music (`applemusic_top`, `applemusic_daily`, `applemusic_albums`), iTunes (`itunes_top`, `itunes_albums`), YouTube (`youtube_tracks`, `youtube_videos`, `youtube_trends`), and Shazam (`shazam`). Date range up to 365 days between `since` and `until`. Response shape: `{ obj: { data: { entries: [...], uniqueEntities: [...] }, length } }`. `shazam` preserves its legacy shape — snake_case entry fields and a `uniqueTracks` rollup in place of `uniqueEntities`.", "parameters": [ { "name": "type", "in": "path", "schema": { "type": "string", "enum": [ "spotify_viral_daily", "spotify_viral_weekly", "spotify_top_daily", "spotify_top_weekly", "applemusic_top", "applemusic_daily", "applemusic_albums", "itunes_top", "itunes_albums", "shazam", "beatport", "youtube", "youtube_tracks", "youtube_videos", "youtube_trends", "amazon" ], "description": "Chart type. One of `spotify_viral_daily`, `spotify_viral_weekly`, `spotify_top_daily`, `spotify_top_weekly`, `applemusic_top`, `applemusic_daily`, `applemusic_albums`, `itunes_top`, `itunes_albums`, `shazam`, `beatport`, `youtube`, `youtube_tracks`, `youtube_videos`, `youtube_trends`, `amazon`. Selects platform + chart kind (e.g. `spotify_viral_daily`, `applemusic_albums`, `youtube_trends`)." }, "required": true, "description": "Chart type. One of `spotify_viral_daily`, `spotify_viral_weekly`, `spotify_top_daily`, `spotify_top_weekly`, `applemusic_top`, `applemusic_daily`, `applemusic_albums`, `itunes_top`, `itunes_albums`, `shazam`, `beatport`, `youtube`, `youtube_tracks`, `youtube_videos`, `youtube_trends`, `amazon`. Selects platform + chart kind (e.g. `spotify_viral_daily`, `applemusic_albums`, `youtube_trends`).", "examples": { "default": { "value": "spotify_viral_daily" } } }, { "name": "id", "in": "path", "schema": { "type": "integer", "minimum": 2, "maximum": 2147483647, "not": { "enum": [ 1 ] }, "description": "Chartmetric artist ID. Note: id=1 ('Various Artists') is rejected." }, "required": true, "description": "Chartmetric artist ID. Note: id=1 ('Various Artists') is rejected.", "examples": { "default": { "value": 2 } } }, { "name": "since", "in": "query", "schema": { "type": "string", "format": "date", "description": "Start date in ISO format (e.g. '2025-11-01'). Defaults to 180 days ago. Window must not exceed 365 days.", "default": "2026-05-09" }, "required": false, "description": "Start date in ISO format (e.g. '2025-11-01'). Defaults to 180 days ago. Window must not exceed 365 days." }, { "name": "until", "in": "query", "schema": { "type": "string", "format": "date", "description": "End date in ISO format (e.g. '2025-11-15'). Defaults to today. Window must not exceed 365 days from `since`.", "default": "2026-11-05" }, "required": false, "description": "End date in ISO format (e.g. '2025-11-15'). Defaults to today. Window must not exceed 365 days from `since`." }, { "name": "duration", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "daily", "weekly", "monthly", "semi-yearly", "yearly", "all_time" ], "description": "Optional chart duration when applicable. One of `daily`, `weekly`, `monthly`, `semi-yearly`, `yearly`, `all_time` or null." }, "required": false, "description": "Optional chart duration when applicable. One of `daily`, `weekly`, `monthly`, `semi-yearly`, `yearly`, `all_time` or null." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "object", "properties": { "data": { "type": [ "object", "null" ], "properties": { "entries": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "rank": { "type": [ "integer", "null" ], "description": "Position on the chart for this entry." }, "added_at": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Date the entry was recorded (ISO 8601)." }, "code2": { "type": [ "string", "null" ], "description": "Country code (ISO 3166-1 alpha-2) for the chart, if applicable." }, "plays": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Play count at the time of the chart snapshot. May arrive as string." }, "duration": { "type": [ "string", "null" ], "description": "Chart duration cadence (e.g. `daily`, `weekly`)." }, "chart_type": { "type": [ "string", "null" ], "description": "Chart type (e.g. `regional`, `viral`, `top`, `trending_video`)." }, "chart_name": { "type": [ "string", "null" ], "description": "Display name of the chart." }, "gnp": { "type": [ "string", "null" ], "description": "GNP value when reported by the source chart." }, "pre_rank": { "type": [ "integer", "null" ], "description": "Rank in the immediately previous snapshot." }, "peak_rank": { "type": [ "integer", "null" ], "description": "Best rank ever achieved on this chart." }, "peak_date": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Date when `peak_rank` was achieved (ISO 8601)." }, "peak_plays": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Play count at peak rank. May arrive as string." }, "total_plays": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Total plays across the chart history. May arrive as string." }, "id": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Internal entry ID. Deprecated." }, "cm_track": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Chartmetric track ID." }, "cm_album": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Chartmetric album ID for the entry, if applicable." }, "name": { "type": [ "string", "null" ], "description": "Track or album name." }, "isrc": { "type": [ "string", "null" ], "description": "International Standard Recording Code for the track." }, "image_url": { "type": [ "string", "null" ], "description": "Track/album cover image URL." }, "spotify_popularity": { "type": [ "integer", "null" ], "description": "Spotify popularity score (0–100)." }, "spotify_artist_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Spotify artist names for the entry." }, "track_genre": { "anyOf": [ { "type": "string" }, { "type": "array", "items": {} } ], "nullable": true, "description": "Track genres (comma-joined string or array)." }, "cm_artist": { "type": [ "array", "null" ], "items": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "description": "List of Chartmetric artist IDs credited on the entry." }, "artist_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Names of credited artists, parallel to `cm_artist`." }, "code2s": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Country codes of credited artists, parallel to `cm_artist`." }, "artist_images": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Image URLs of credited artists." }, "artist_covers": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Cover image URLs of credited artists." }, "spotify_artist_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Spotify artist IDs of credited artists." }, "spotify_track_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Spotify track IDs for the entry." }, "spotify_album_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Spotify album IDs containing the track." }, "spotify_album_id": { "type": [ "string", "null" ], "description": "Primary Spotify album ID for the track." }, "spotify_id": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Internal Chartmetric track ID. Deprecated." }, "spotify_duration_ms": { "type": [ "integer", "null" ], "description": "Spotify track duration in milliseconds." }, "album_ids": { "type": [ "array", "null" ], "items": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "description": "Chartmetric album IDs containing the track." }, "album_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Album names parallel to `album_ids`." }, "album_upc": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Album UPCs parallel to `album_ids`." }, "album_label": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Album record labels parallel to `album_ids`." }, "release_dates": { "type": [ "array", "null" ], "items": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ] }, "description": "Release dates parallel to `album_ids`." } } }, "description": "List of chart entries for the artist within the requested window." }, "uniqueEntities": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "entityId": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 2147483647 }, { "type": "string" } ], "nullable": true, "description": "Chartmetric entity ID (track or album, depending on chart type)." }, "name": { "type": [ "string", "null" ], "description": "Display name of the entity." }, "imageUrl": { "type": [ "string", "null" ], "description": "Cover image URL." }, "chartEvents": { "type": [ "integer", "null" ], "minimum": 0, "description": "Number of distinct chart appearances within the requested window." } } }, "description": "Distinct entity rollup with chart-event counts." } }, "description": "Chart payload from the underlying ClickHouse query." }, "length": { "type": "integer", "minimum": 0, "description": "Reported length of the chart payload." } }, "required": [ "length" ] } }, "additionalProperties": false }, "examples": { "default": { "value": { "obj": { "data": { "entries": [ { "spotify_id": 14455213, "rank": 111, "added_at": "2020-03-03T08:00:00.000Z", "code2": "AU", "plays": 40234, "duration": "daily", "chart_type": "regional", "chart_name": "DAILY", "gnp": "351182.00", "pre_rank": 117, "peak_rank": 73, "peak_date": "2019-12-05T08:00:00.000Z", "peak_plays": 58816, "total_plays": "7805075", "id": 14455213, "name": "Woke Up Late (feat. Hailee Steinfeld)", "isrc": "QMCE31801829", "spotify_album_id": "5gdsguQxwQQlpTi1SU3tbY", "image_url": "https://i.scdn.co/image/5b41143718f3e76ddf0bf10600ca511102a0a105", "spotify_popularity": 62, "cm_track": 22310714, "spotify_artist_names": [ "Drax Project", "Hailee Steinfeld" ], "track_genre": "dance pop,pop,post-teen pop,australian pop,nz pop", "cm_artist": [ 210051, 4904 ], "artist_names": [ "Drax Project", "Hailee Steinfeld" ], "code2s": [ "NZ", "US" ], "spotify_artist_ids": [ "6S0IvKlvPMX1RtAYtVpUV8", "5p7f24Rk5HkUZsaS3BLG5F" ], "spotify_track_ids": [ "4oPWkP9zQ5ANBbfdHGOvKF" ], "spotify_album_ids": [ "5gdsguQxwQQlpTi1SU3tbY" ], "spotify_duration_ms": 181826, "album_ids": [ 4883983 ], "album_names": [ "Drax Project" ], "album_upc": [ "814908028765" ], "album_label": [ "300 Entertainment" ], "release_dates": [ "2019-09-27T07:00:00.000Z" ] } ], "uniqueEntities": [ { "entityId": "22310714", "name": "Woke Up Late (feat. Hailee Steinfeld)", "imageUrl": "https://i.scdn.co/image/5b41143718f3e76ddf0bf10600ca511102a0a105", "chartEvents": 2 } ] }, "length": 1 } } } } } } } } } }, "/api/artist/{type}/{id}/get-ids": { "get": { "summary": "Get Cross-Platform Artist IDs", "tags": [ "Artist" ], "operationId": "getArtistIds", "description": "Resolve cross-platform artist IDs from any single source. `type` accepts `chartmetric`, `spotify`, `itunes`, `deezer`, `amazon`, `youtube` (or `youtube-channel`), and `instagram`. When `aggregate=true`, domain arrays are pre-aggregated into a single row; otherwise one row per linked id is returned.", "parameters": [ { "name": "type", "in": "path", "schema": { "type": "string", "enum": [ "chartmetric", "spotify", "itunes", "deezer", "amazon", "youtube" ], "description": "Source identifier type. One of `chartmetric`, `spotify`, `itunes`, `deezer`, `amazon`, `youtube`. `youtube` expects the channel ID, not the artist ID." }, "required": true, "description": "Source identifier type. One of `chartmetric`, `spotify`, `itunes`, `deezer`, `amazon`, `youtube`. `youtube` expects the channel ID, not the artist ID.", "examples": { "default": { "value": "chartmetric" } } }, { "name": "id", "in": "path", "schema": { "anyOf": [ { "type": "integer", "minimum": 2, "maximum": 2147483647, "not": { "enum": [ 1 ] }, "description": "Chartmetric artist ID. Note: id=1 ('Various Artists') is rejected.", "x-required": true }, { "type": "integer", "x-required": true }, { "type": "string", "pattern": "^[a-zA-Z0-9-_]+$", "x-required": true } ], "description": "Artist identifier whose format depends on `type` — numeric for `chartmetric`/`deezer`/`itunes`, alphanumeric/dashed string for `amazon`/`spotify`/`youtube`." }, "required": true, "description": "Artist identifier whose format depends on `type` — numeric for `chartmetric`/`deezer`/`itunes`, alphanumeric/dashed string for `amazon`/`spotify`/`youtube`.", "examples": { "default": { "value": 2 } } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Number of entries to skip. Applied only when `aggregate=false`." }, "required": false, "description": "Number of entries to skip. Applied only when `aggregate=false`." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "Maximum number of entries to return when `aggregate=false`. Defaults to 10000, max 10000. Has no effect when `aggregate=true`.", "default": 10000 }, "required": false, "description": "Maximum number of entries to return when `aggregate=false`. Defaults to 10000, max 10000. Has no effect when `aggregate=true`." }, { "name": "aggregate", "in": "query", "schema": { "type": "boolean", "description": "If true, returns a single row with platform IDs aggregated into arrays. Deprecated — preserved for backwards compatibility.", "default": false }, "required": false, "description": "If true, returns a single row with platform IDs aggregated into arrays. Deprecated — preserved for backwards compatibility." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "array", "items": { "type": "object", "properties": { "cm_artist": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Chartmetric artist ID. Present when `aggregate=false`." }, "chartmetric_id": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Chartmetric artist ID. Present when `aggregate=true`." }, "artist_name": { "type": [ "string", "null" ], "description": "Artist name. Present when `aggregate=false`." }, "spotify_artist_id": { "type": [ "string", "null" ], "description": "Spotify artist ID. Present when `aggregate=false`." }, "itunes_artist_id": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "iTunes artist ID. Present when `aggregate=false`." }, "deezer_artist_id": { "type": [ "string", "null" ], "description": "Deezer artist ID. Present when `aggregate=false`." }, "amazon_artist_id": { "type": [ "string", "null" ], "description": "Amazon artist ID. Present when `aggregate=false`." }, "youtube_channel_id": { "type": [ "string", "null" ], "description": "YouTube channel ID. Present when `aggregate=false`." }, "instagram_id": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Instagram numeric user ID. Present in aggregate responses." }, "spotify_artist_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Aggregated list of Spotify artist IDs. Present when `aggregate=true`." }, "itunes_artist_ids": { "type": [ "array", "null" ], "items": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ] }, "description": "Aggregated list of iTunes artist IDs. Present when `aggregate=true`." }, "deezer_artist_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Aggregated list of Deezer artist IDs. Present when `aggregate=true`." }, "amazon_artist_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Aggregated list of Amazon artist IDs. Present when `aggregate=true`." }, "youtube_channel_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Aggregated list of YouTube channel IDs. Present when `aggregate=true`." } } } } }, "required": [ "obj" ], "additionalProperties": false }, "examples": { "default": { "value": { "obj": [ { "chartmetric_id": 4904, "artist_name": "Hailee Steinfeld", "spotify_artist_ids": [ "5p7f24Rk5HkUZsaS3BLG5F" ], "itunes_artist_ids": [ 417571723 ], "deezer_artist_ids": [ "5961630" ], "amazon_artist_ids": [ "B00L4I14C0", "B00L48A8F4" ], "youtube_channel_ids": [ "UCWfytcGFwPSMwvP5HYuXGqw" ], "instagram_id": 2274763833 } ] } } } } } } } } }, "/api/artist/{type}/list": { "get": { "summary": "List Artists by Stat Range", "tags": [ "Artist" ], "operationId": "listArtistsByType", "description": "Sample of artists filtered by a single metric (`type`) within `[min, max]` plus optional city / code2 / genre filters. When the query has no matches, `data` is the sentinel string `\"No artists found with given parameters.\"` and `length` is `-1`.", "parameters": [ { "name": "type", "in": "path", "schema": { "type": "string", "enum": [ "sp_followers", "sp_monthly_listeners", "sp_popularity", "sp_listeners_to_followers_ratio", "sp_followers_to_listeners_ratio", "deezer_fans", "fs_likes", "fs_talks", "ins_followers", "ts_followers", "ts_retweets", "ycs_views", "ycs_subscribers", "youtube_daily_video_views", "youtube_monthly_video_views", "ws_views", "soundcloud_followers", "bs_followers", "tiktok_followers", "tiktok_likes", "cm_artist_rank" ], "description": "Stat to filter on. One of `sp_followers`, `sp_monthly_listeners`, `sp_popularity`, `sp_listeners_to_followers_ratio`, `sp_followers_to_listeners_ratio`, `deezer_fans`, `fs_likes`, `fs_talks`, `ins_followers`, `ts_followers`, `ts_retweets`, `ycs_views`, `ycs_subscribers`, `youtube_daily_video_views`, `youtube_monthly_video_views`, `ws_views`, `soundcloud_followers`, `bs_followers`, `tiktok_followers`, `tiktok_likes`, `cm_artist_rank` (e.g. `cm_artist_rank`, `sp_followers`, `sp_monthly_listeners`)." }, "required": true, "description": "Stat to filter on. One of `sp_followers`, `sp_monthly_listeners`, `sp_popularity`, `sp_listeners_to_followers_ratio`, `sp_followers_to_listeners_ratio`, `deezer_fans`, `fs_likes`, `fs_talks`, `ins_followers`, `ts_followers`, `ts_retweets`, `ycs_views`, `ycs_subscribers`, `youtube_daily_video_views`, `youtube_monthly_video_views`, `ws_views`, `soundcloud_followers`, `bs_followers`, `tiktok_followers`, `tiktok_likes`, `cm_artist_rank` (e.g. `cm_artist_rank`, `sp_followers`, `sp_monthly_listeners`).", "examples": { "default": { "value": "sp_followers" } } }, { "name": "min", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Minimum value (inclusive) for the stat selected by `type`." }, "required": true, "description": "Minimum value (inclusive) for the stat selected by `type`.", "examples": { "default": { "value": 1 } } }, { "name": "max", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Maximum value (inclusive) for the stat selected by `type`." }, "required": true, "description": "Maximum value (inclusive) for the stat selected by `type`.", "examples": { "default": { "value": 1 } } }, { "name": "code2", "in": "query", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB')." }, "required": false, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB')." }, { "name": "genreId", "in": "query", "schema": { "type": [ "integer", "null" ], "description": "Filter by Chartmetric genre ID." }, "required": false, "description": "Filter by Chartmetric genre ID." }, { "name": "subGenreId", "in": "query", "schema": { "type": [ "integer", "null" ], "description": "Filter by Chartmetric sub-genre ID." }, "required": false, "description": "Filter by Chartmetric sub-genre ID." }, { "name": "city", "in": "query", "schema": { "type": "string", "description": "City name filter applied to the artist top-listener city." }, "required": false, "description": "City name filter applied to the artist top-listener city." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 100000, "description": "Number of entries to skip. Bounded by the public API offset limit." }, "required": false, "description": "Number of entries to skip. Bounded by the public API offset limit." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "description": "Maximum number of artists to return. Defaults to the public API default; max 200.", "default": 10 }, "required": false, "description": "Maximum number of artists to return. Defaults to the public API default; max 200." }, { "name": "unsigned", "in": "query", "schema": { "type": "boolean", "description": "If true, restrict to unsigned artists. Defaults to false.", "default": false }, "required": false, "description": "If true, restrict to unsigned artists. Defaults to false." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "object", "properties": { "length": { "type": "integer", "description": "Number of items in `data`, or `-1` when no artists matched (in which case `data` is the sentinel string)." }, "data": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "chartmetric_artist_id": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Chartmetric artist ID." }, "name": { "type": [ "string", "null" ], "description": "Artist name." }, "code2": { "type": [ "string", "null" ], "description": "Artist country (ISO 3166-1 alpha-2)." }, "genres": { "anyOf": [ { "type": "string" }, { "type": "array", "items": {} } ], "nullable": true, "description": "Genres for the artist (comma-joined string or array)." }, "cpp_rank": { "type": [ "integer", "null" ], "description": "Chartmetric Cross-Platform Performance rank." }, "rank_eg": { "type": [ "integer", "null" ], "description": "Chartmetric engagement rank." }, "rank_fb": { "type": [ "integer", "null" ], "description": "Chartmetric fan-base rank." }, "spotify_popularity": { "type": [ "integer", "null" ], "description": "Spotify popularity score (0–100)." }, "spotify_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Spotify follower count. May arrive as string (uncast aggregate)." }, "spotify_monthly_listeners": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Spotify monthly listener count. May arrive as string." }, "spotify_listeners_to_followers_ratio": { "type": [ "number", "null" ], "format": "float", "description": "Ratio of Spotify monthly listeners to followers." }, "spotify_followers_to_listeners_ratio": { "type": [ "number", "null" ], "format": "float", "description": "Ratio of Spotify followers to monthly listeners." }, "deezer_fans": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Deezer fan count. May arrive as string." }, "facebook_likes": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Facebook page-likes count. May arrive as string." }, "facebook_talks": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Facebook people-talking-about count. May arrive as string." }, "twitter_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Twitter/X follower count. May arrive as string." }, "twitter_retweets": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Twitter/X retweet count. May arrive as string." }, "instagram_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Instagram follower count. May arrive as string." }, "youtube_channel_views": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "YouTube channel view count. May arrive as string." }, "youtube_subscribers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "YouTube channel subscriber count. May arrive as string." }, "youtube_daily_video_views": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "YouTube daily video views (rolling). May arrive as string." }, "youtube_monthly_video_views": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "YouTube monthly video views (rolling). May arrive as string." }, "wikipedia_views": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Wikipedia page-view count. May arrive as string." }, "soundcloud_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "SoundCloud follower count. May arrive as string." }, "bandsintown_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Bandsintown follower count. May arrive as string." }, "tiktok_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "TikTok follower count. May arrive as string." }, "tiktok_likes": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "TikTok like count. May arrive as string." }, "sp_where_people_listen": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "code2": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-2 country code of the listener location." }, "listeners": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Spotify monthly listener count for this location. May arrive as string (uncast aggregate)." }, "name": { "type": [ "string", "null" ], "description": "City or country name of the listener location." } } }, "description": "Top Spotify listener locations for this artist (city + country snapshots)." }, "signed": { "type": [ "boolean", "null" ], "description": "Whether the artist has been signed to a record label." } } } }, { "type": "string" } ], "description": "List of matched artists, or the sentinel string `\"No artists found with given parameters.\"` when there are no matches." } }, "required": [ "length", "data" ] } }, "additionalProperties": false }, "examples": { "default": { "value": { "obj": { "length": 200, "data": [ { "chartmetric_artist_id": 41457, "name": "Neamen Lyles", "code2": "US", "genres": "deep smooth jazz, smooth jazz, jazz", "cpp_rank": 375487, "rank_eg": 451348, "rank_fb": 282213, "spotify_popularity": 15, "spotify_followers": 500, "spotify_monthly_listeners": 3652, "spotify_listeners_to_followers_ratio": 7.304, "spotify_followers_to_listeners_ratio": 0.1369, "deezer_fans": "28", "facebook_likes": null, "facebook_talks": null, "twitter_followers": null, "twitter_retweets": null, "instagram_followers": null, "youtube_channel_views": null, "youtube_subscribers": null, "youtube_daily_video_views": null, "youtube_monthly_video_views": null, "wikipedia_views": null, "soundcloud_followers": null, "bandsintown_followers": null, "tiktok_followers": null, "tiktok_likes": null, "sp_where_people_listen": [ { "code2": "id", "listeners": 48, "name": "Jakarta" } ], "signed": false } ] } } } } } } } } } }, "/api/artist/list/filter": { "get": { "summary": "List Artists (with filters)", "tags": [ "Artist" ], "operationId": "listArtistsByFilter", "description": "List artists matching a set of filters on per-period stats (`latest` / `weekly_diff` / `monthly_diff` / `*_percent`) across ~60 supported metrics. `sortColumn` accepts `.`. Response is double-wrapped (`{ obj: { obj: [...], offset, total } }`) for backwards compatibility with legacy clients — inner object contains the result page plus pagination counters. Result set capped at 10,000 (`limit + offset <= 10000`).", "parameters": [ { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Number of entries to skip. Capped so `limit + offset` does not exceed 10,000 (Elasticsearch max window)." }, "required": false, "description": "Number of entries to skip. Capped so `limit + offset` does not exceed 10,000 (Elasticsearch max window)." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 0, "description": "Maximum number of artists to return. Defaults to 50, max 200.", "default": 50 }, "required": false, "description": "Maximum number of artists to return. Defaults to 50, max 200." }, { "name": "eventIds[]", "in": "query", "schema": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "description": "Restrict to artists associated with any of these Chartmetric event IDs (e.g. festival lineups)." }, "required": false, "description": "Restrict to artists associated with any of these Chartmetric event IDs (e.g. festival lineups)." }, { "name": "tagId", "in": "query", "schema": { "type": "integer", "description": "Filter by parent genre (Chartmetric genre ID)." }, "required": false, "description": "Filter by parent genre (Chartmetric genre ID)." }, { "name": "subTagId", "in": "query", "schema": { "type": "integer", "description": "Filter by sub-genre (Chartmetric sub-genre ID)." }, "required": false, "description": "Filter by sub-genre (Chartmetric sub-genre ID)." }, { "name": "code2", "in": "query", "schema": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB')." }, "required": false, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB')." }, { "name": "firstReleaseDaysAgo", "in": "query", "schema": { "type": "integer", "description": "Restrict to artists whose first release falls within this many days of today. Filters on the artist's debut release date." }, "required": false, "description": "Restrict to artists whose first release falls within this many days of today. Filters on the artist's debut release date." }, { "name": "pronoun", "in": "query", "schema": { "type": "string", "enum": [ "any", "others", "notSpecified", "he/him", "she/her", "they/them" ], "description": "Filter by artist pronoun. One of `any`, `others`, `notSpecified`, `he/him`, `she/her`, `they/them`." }, "required": false, "description": "Filter by artist pronoun. One of `any`, `others`, `notSpecified`, `he/him`, `she/her`, `they/them`." }, { "name": "band", "in": "query", "schema": { "type": "boolean", "description": "If true, return only band-type artist profiles; if false, only solo artists. Omit to return both." }, "required": false, "description": "If true, return only band-type artist profiles; if false, only solo artists. Omit to return both." }, { "name": "sortColumn", "in": "query", "schema": { "type": "string", "enum": [ "amazon_ed_playlist_count", "amazon_playlist_count", "boomplay_comments", "boomplay_favorites", "boomplay_plays", "boomplay_ranking_current", "boomplay_shares", "bs_followers", "deezer_ed_playlist_count", "deezer_ed_playlist_total_reach", "deezer_fans", "deezer_playlist_count", "deezer_playlist_total_reach", "facebook_followers", "fs_likes", "fs_talks", "genius_pageviews", "ins_engagement_rate", "ins_followers", "itunes_ed_playlist_count", "itunes_playlist_count", "line_music_artist_likes", "line_music_likes", "line_music_mv_plays", "line_music_plays", "melon_artist_fans", "melon_likes", "melon_video_likes", "melon_video_views", "pandora_lifetime_stations_added", "pandora_lifetime_streams", "pandora_listeners_28_day", "shazam_count", "songkick_fans", "soundcloud_followers", "soundcloud_plays", "sp_followers", "sp_followers_to_listeners_ratio", "sp_listeners_to_followers_ratio", "sp_monthly_listeners", "sp_popularity", "spotify_ed_playlist_count", "spotify_ed_playlist_total_reach", "spotify_playlist_count", "spotify_playlist_total_reach", "tiktok_followers", "tiktok_likes", "tiktok_top_video_views", "tiktok_track_posts", "ts_followers", "ts_likes", "ts_tweet_count", "twitch_followers", "twitch_monthly_viewer_hours", "twitch_views", "twitch_weekly_viewer_hours", "ws_views", "ycs_subscribers", "ycs_views", "youtube_daily_video_views", "youtube_ed_playlist_count", "youtube_ed_playlist_total_reach", "youtube_monthly_video_views", "youtube_playlist_count", "youtube_playlist_total_reach", "snap_subscribers", "anghami_followers", "anghami_plays", "latest.amazon_ed_playlist_count", "latest.amazon_playlist_count", "latest.boomplay_comments", "latest.boomplay_favorites", "latest.boomplay_plays", "latest.boomplay_ranking_current", "latest.boomplay_shares", "latest.bs_followers", "latest.deezer_ed_playlist_count", "latest.deezer_ed_playlist_total_reach", "latest.deezer_fans", "latest.deezer_playlist_count", "latest.deezer_playlist_total_reach", "latest.facebook_followers", "latest.fs_likes", "latest.fs_talks", "latest.genius_pageviews", "latest.ins_engagement_rate", "latest.ins_followers", "latest.itunes_ed_playlist_count", "latest.itunes_playlist_count", "latest.line_music_artist_likes", "latest.line_music_likes", "latest.line_music_mv_plays", "latest.line_music_plays", "latest.melon_artist_fans", "latest.melon_likes", "latest.melon_video_likes", "latest.melon_video_views", "latest.pandora_lifetime_stations_added", "latest.pandora_lifetime_streams", "latest.pandora_listeners_28_day", "latest.shazam_count", "latest.songkick_fans", "latest.soundcloud_followers", "latest.soundcloud_plays", "latest.sp_followers", "latest.sp_followers_to_listeners_ratio", "latest.sp_listeners_to_followers_ratio", "latest.sp_monthly_listeners", "latest.sp_popularity", "latest.spotify_ed_playlist_count", "latest.spotify_ed_playlist_total_reach", "latest.spotify_playlist_count", "latest.spotify_playlist_total_reach", "latest.tiktok_followers", "latest.tiktok_likes", "latest.tiktok_top_video_views", "latest.tiktok_track_posts", "latest.ts_followers", "latest.ts_likes", "latest.ts_tweet_count", "latest.twitch_followers", "latest.twitch_monthly_viewer_hours", "latest.twitch_views", "latest.twitch_weekly_viewer_hours", "latest.ws_views", "latest.ycs_subscribers", "latest.ycs_views", "latest.youtube_daily_video_views", "latest.youtube_ed_playlist_count", "latest.youtube_ed_playlist_total_reach", "latest.youtube_monthly_video_views", "latest.youtube_playlist_count", "latest.youtube_playlist_total_reach", "latest.snap_subscribers", "latest.anghami_followers", "latest.anghami_plays", "weekly_diff.amazon_ed_playlist_count", "weekly_diff.amazon_playlist_count", "weekly_diff.boomplay_comments", "weekly_diff.boomplay_favorites", "weekly_diff.boomplay_plays", "weekly_diff.boomplay_ranking_current", "weekly_diff.boomplay_shares", "weekly_diff.bs_followers", "weekly_diff.deezer_ed_playlist_count", "weekly_diff.deezer_ed_playlist_total_reach", "weekly_diff.deezer_fans", "weekly_diff.deezer_playlist_count", "weekly_diff.deezer_playlist_total_reach", "weekly_diff.facebook_followers", "weekly_diff.fs_likes", "weekly_diff.fs_talks", "weekly_diff.genius_pageviews", "weekly_diff.ins_engagement_rate", "weekly_diff.ins_followers", "weekly_diff.itunes_ed_playlist_count", "weekly_diff.itunes_playlist_count", "weekly_diff.line_music_artist_likes", "weekly_diff.line_music_likes", "weekly_diff.line_music_mv_plays", "weekly_diff.line_music_plays", "weekly_diff.melon_artist_fans", "weekly_diff.melon_likes", "weekly_diff.melon_video_likes", "weekly_diff.melon_video_views", "weekly_diff.pandora_lifetime_stations_added", "weekly_diff.pandora_lifetime_streams", "weekly_diff.pandora_listeners_28_day", "weekly_diff.shazam_count", "weekly_diff.songkick_fans", "weekly_diff.soundcloud_followers", "weekly_diff.soundcloud_plays", "weekly_diff.sp_followers", "weekly_diff.sp_followers_to_listeners_ratio", "weekly_diff.sp_listeners_to_followers_ratio", "weekly_diff.sp_monthly_listeners", "weekly_diff.sp_popularity", "weekly_diff.spotify_ed_playlist_count", "weekly_diff.spotify_ed_playlist_total_reach", "weekly_diff.spotify_playlist_count", "weekly_diff.spotify_playlist_total_reach", "weekly_diff.tiktok_followers", "weekly_diff.tiktok_likes", "weekly_diff.tiktok_top_video_views", "weekly_diff.tiktok_track_posts", "weekly_diff.ts_followers", "weekly_diff.ts_likes", "weekly_diff.ts_tweet_count", "weekly_diff.twitch_followers", "weekly_diff.twitch_monthly_viewer_hours", "weekly_diff.twitch_views", "weekly_diff.twitch_weekly_viewer_hours", "weekly_diff.ws_views", "weekly_diff.ycs_subscribers", "weekly_diff.ycs_views", "weekly_diff.youtube_daily_video_views", "weekly_diff.youtube_ed_playlist_count", "weekly_diff.youtube_ed_playlist_total_reach", "weekly_diff.youtube_monthly_video_views", "weekly_diff.youtube_playlist_count", "weekly_diff.youtube_playlist_total_reach", "weekly_diff.snap_subscribers", "weekly_diff.anghami_followers", "weekly_diff.anghami_plays", "weekly_diff_percent.amazon_ed_playlist_count", "weekly_diff_percent.amazon_playlist_count", "weekly_diff_percent.boomplay_comments", "weekly_diff_percent.boomplay_favorites", "weekly_diff_percent.boomplay_plays", "weekly_diff_percent.boomplay_ranking_current", "weekly_diff_percent.boomplay_shares", "weekly_diff_percent.bs_followers", "weekly_diff_percent.deezer_ed_playlist_count", "weekly_diff_percent.deezer_ed_playlist_total_reach", "weekly_diff_percent.deezer_fans", "weekly_diff_percent.deezer_playlist_count", "weekly_diff_percent.deezer_playlist_total_reach", "weekly_diff_percent.facebook_followers", "weekly_diff_percent.fs_likes", "weekly_diff_percent.fs_talks", "weekly_diff_percent.genius_pageviews", "weekly_diff_percent.ins_engagement_rate", "weekly_diff_percent.ins_followers", "weekly_diff_percent.itunes_ed_playlist_count", "weekly_diff_percent.itunes_playlist_count", "weekly_diff_percent.line_music_artist_likes", "weekly_diff_percent.line_music_likes", "weekly_diff_percent.line_music_mv_plays", "weekly_diff_percent.line_music_plays", "weekly_diff_percent.melon_artist_fans", "weekly_diff_percent.melon_likes", "weekly_diff_percent.melon_video_likes", "weekly_diff_percent.melon_video_views", "weekly_diff_percent.pandora_lifetime_stations_added", "weekly_diff_percent.pandora_lifetime_streams", "weekly_diff_percent.pandora_listeners_28_day", "weekly_diff_percent.shazam_count", "weekly_diff_percent.songkick_fans", "weekly_diff_percent.soundcloud_followers", "weekly_diff_percent.soundcloud_plays", "weekly_diff_percent.sp_followers", "weekly_diff_percent.sp_followers_to_listeners_ratio", "weekly_diff_percent.sp_listeners_to_followers_ratio", "weekly_diff_percent.sp_monthly_listeners", "weekly_diff_percent.sp_popularity", "weekly_diff_percent.spotify_ed_playlist_count", "weekly_diff_percent.spotify_ed_playlist_total_reach", "weekly_diff_percent.spotify_playlist_count", "weekly_diff_percent.spotify_playlist_total_reach", "weekly_diff_percent.tiktok_followers", "weekly_diff_percent.tiktok_likes", "weekly_diff_percent.tiktok_top_video_views", "weekly_diff_percent.tiktok_track_posts", "weekly_diff_percent.ts_followers", "weekly_diff_percent.ts_likes", "weekly_diff_percent.ts_tweet_count", "weekly_diff_percent.twitch_followers", "weekly_diff_percent.twitch_monthly_viewer_hours", "weekly_diff_percent.twitch_views", "weekly_diff_percent.twitch_weekly_viewer_hours", "weekly_diff_percent.ws_views", "weekly_diff_percent.ycs_subscribers", "weekly_diff_percent.ycs_views", "weekly_diff_percent.youtube_daily_video_views", "weekly_diff_percent.youtube_ed_playlist_count", "weekly_diff_percent.youtube_ed_playlist_total_reach", "weekly_diff_percent.youtube_monthly_video_views", "weekly_diff_percent.youtube_playlist_count", "weekly_diff_percent.youtube_playlist_total_reach", "weekly_diff_percent.snap_subscribers", "weekly_diff_percent.anghami_followers", "weekly_diff_percent.anghami_plays", "monthly_diff.amazon_ed_playlist_count", "monthly_diff.amazon_playlist_count", "monthly_diff.boomplay_comments", "monthly_diff.boomplay_favorites", "monthly_diff.boomplay_plays", "monthly_diff.boomplay_ranking_current", "monthly_diff.boomplay_shares", "monthly_diff.bs_followers", "monthly_diff.deezer_ed_playlist_count", "monthly_diff.deezer_ed_playlist_total_reach", "monthly_diff.deezer_fans", "monthly_diff.deezer_playlist_count", "monthly_diff.deezer_playlist_total_reach", "monthly_diff.facebook_followers", "monthly_diff.fs_likes", "monthly_diff.fs_talks", "monthly_diff.genius_pageviews", "monthly_diff.ins_engagement_rate", "monthly_diff.ins_followers", "monthly_diff.itunes_ed_playlist_count", "monthly_diff.itunes_playlist_count", "monthly_diff.line_music_artist_likes", "monthly_diff.line_music_likes", "monthly_diff.line_music_mv_plays", "monthly_diff.line_music_plays", "monthly_diff.melon_artist_fans", "monthly_diff.melon_likes", "monthly_diff.melon_video_likes", "monthly_diff.melon_video_views", "monthly_diff.pandora_lifetime_stations_added", "monthly_diff.pandora_lifetime_streams", "monthly_diff.pandora_listeners_28_day", "monthly_diff.shazam_count", "monthly_diff.songkick_fans", "monthly_diff.soundcloud_followers", "monthly_diff.soundcloud_plays", "monthly_diff.sp_followers", "monthly_diff.sp_followers_to_listeners_ratio", "monthly_diff.sp_listeners_to_followers_ratio", "monthly_diff.sp_monthly_listeners", "monthly_diff.sp_popularity", "monthly_diff.spotify_ed_playlist_count", "monthly_diff.spotify_ed_playlist_total_reach", "monthly_diff.spotify_playlist_count", "monthly_diff.spotify_playlist_total_reach", "monthly_diff.tiktok_followers", "monthly_diff.tiktok_likes", "monthly_diff.tiktok_top_video_views", "monthly_diff.tiktok_track_posts", "monthly_diff.ts_followers", "monthly_diff.ts_likes", "monthly_diff.ts_tweet_count", "monthly_diff.twitch_followers", "monthly_diff.twitch_monthly_viewer_hours", "monthly_diff.twitch_views", "monthly_diff.twitch_weekly_viewer_hours", "monthly_diff.ws_views", "monthly_diff.ycs_subscribers", "monthly_diff.ycs_views", "monthly_diff.youtube_daily_video_views", "monthly_diff.youtube_ed_playlist_count", "monthly_diff.youtube_ed_playlist_total_reach", "monthly_diff.youtube_monthly_video_views", "monthly_diff.youtube_playlist_count", "monthly_diff.youtube_playlist_total_reach", "monthly_diff.snap_subscribers", "monthly_diff.anghami_followers", "monthly_diff.anghami_plays", "monthly_diff_percent.amazon_ed_playlist_count", "monthly_diff_percent.amazon_playlist_count", "monthly_diff_percent.boomplay_comments", "monthly_diff_percent.boomplay_favorites", "monthly_diff_percent.boomplay_plays", "monthly_diff_percent.boomplay_ranking_current", "monthly_diff_percent.boomplay_shares", "monthly_diff_percent.bs_followers", "monthly_diff_percent.deezer_ed_playlist_count", "monthly_diff_percent.deezer_ed_playlist_total_reach", "monthly_diff_percent.deezer_fans", "monthly_diff_percent.deezer_playlist_count", "monthly_diff_percent.deezer_playlist_total_reach", "monthly_diff_percent.facebook_followers", "monthly_diff_percent.fs_likes", "monthly_diff_percent.fs_talks", "monthly_diff_percent.genius_pageviews", "monthly_diff_percent.ins_engagement_rate", "monthly_diff_percent.ins_followers", "monthly_diff_percent.itunes_ed_playlist_count", "monthly_diff_percent.itunes_playlist_count", "monthly_diff_percent.line_music_artist_likes", "monthly_diff_percent.line_music_likes", "monthly_diff_percent.line_music_mv_plays", "monthly_diff_percent.line_music_plays", "monthly_diff_percent.melon_artist_fans", "monthly_diff_percent.melon_likes", "monthly_diff_percent.melon_video_likes", "monthly_diff_percent.melon_video_views", "monthly_diff_percent.pandora_lifetime_stations_added", "monthly_diff_percent.pandora_lifetime_streams", "monthly_diff_percent.pandora_listeners_28_day", "monthly_diff_percent.shazam_count", "monthly_diff_percent.songkick_fans", "monthly_diff_percent.soundcloud_followers", "monthly_diff_percent.soundcloud_plays", "monthly_diff_percent.sp_followers", "monthly_diff_percent.sp_followers_to_listeners_ratio", "monthly_diff_percent.sp_listeners_to_followers_ratio", "monthly_diff_percent.sp_monthly_listeners", "monthly_diff_percent.sp_popularity", "monthly_diff_percent.spotify_ed_playlist_count", "monthly_diff_percent.spotify_ed_playlist_total_reach", "monthly_diff_percent.spotify_playlist_count", "monthly_diff_percent.spotify_playlist_total_reach", "monthly_diff_percent.tiktok_followers", "monthly_diff_percent.tiktok_likes", "monthly_diff_percent.tiktok_top_video_views", "monthly_diff_percent.tiktok_track_posts", "monthly_diff_percent.ts_followers", "monthly_diff_percent.ts_likes", "monthly_diff_percent.ts_tweet_count", "monthly_diff_percent.twitch_followers", "monthly_diff_percent.twitch_monthly_viewer_hours", "monthly_diff_percent.twitch_views", "monthly_diff_percent.twitch_weekly_viewer_hours", "monthly_diff_percent.ws_views", "monthly_diff_percent.ycs_subscribers", "monthly_diff_percent.ycs_views", "monthly_diff_percent.youtube_daily_video_views", "monthly_diff_percent.youtube_ed_playlist_count", "monthly_diff_percent.youtube_ed_playlist_total_reach", "monthly_diff_percent.youtube_monthly_video_views", "monthly_diff_percent.youtube_playlist_count", "monthly_diff_percent.youtube_playlist_total_reach", "monthly_diff_percent.snap_subscribers", "monthly_diff_percent.anghami_followers", "monthly_diff_percent.anghami_plays", "bimonthly_diff.amazon_ed_playlist_count", "bimonthly_diff.amazon_playlist_count", "bimonthly_diff.boomplay_comments", "bimonthly_diff.boomplay_favorites", "bimonthly_diff.boomplay_plays", "bimonthly_diff.boomplay_ranking_current", "bimonthly_diff.boomplay_shares", "bimonthly_diff.bs_followers", "bimonthly_diff.deezer_ed_playlist_count", "bimonthly_diff.deezer_ed_playlist_total_reach", "bimonthly_diff.deezer_fans", "bimonthly_diff.deezer_playlist_count", "bimonthly_diff.deezer_playlist_total_reach", "bimonthly_diff.facebook_followers", "bimonthly_diff.fs_likes", "bimonthly_diff.fs_talks", "bimonthly_diff.genius_pageviews", "bimonthly_diff.ins_engagement_rate", "bimonthly_diff.ins_followers", "bimonthly_diff.itunes_ed_playlist_count", "bimonthly_diff.itunes_playlist_count", "bimonthly_diff.line_music_artist_likes", "bimonthly_diff.line_music_likes", "bimonthly_diff.line_music_mv_plays", "bimonthly_diff.line_music_plays", "bimonthly_diff.melon_artist_fans", "bimonthly_diff.melon_likes", "bimonthly_diff.melon_video_likes", "bimonthly_diff.melon_video_views", "bimonthly_diff.pandora_lifetime_stations_added", "bimonthly_diff.pandora_lifetime_streams", "bimonthly_diff.pandora_listeners_28_day", "bimonthly_diff.shazam_count", "bimonthly_diff.songkick_fans", "bimonthly_diff.soundcloud_followers", "bimonthly_diff.soundcloud_plays", "bimonthly_diff.sp_followers", "bimonthly_diff.sp_followers_to_listeners_ratio", "bimonthly_diff.sp_listeners_to_followers_ratio", "bimonthly_diff.sp_monthly_listeners", "bimonthly_diff.sp_popularity", "bimonthly_diff.spotify_ed_playlist_count", "bimonthly_diff.spotify_ed_playlist_total_reach", "bimonthly_diff.spotify_playlist_count", "bimonthly_diff.spotify_playlist_total_reach", "bimonthly_diff.tiktok_followers", "bimonthly_diff.tiktok_likes", "bimonthly_diff.tiktok_top_video_views", "bimonthly_diff.tiktok_track_posts", "bimonthly_diff.ts_followers", "bimonthly_diff.ts_likes", "bimonthly_diff.ts_tweet_count", "bimonthly_diff.twitch_followers", "bimonthly_diff.twitch_monthly_viewer_hours", "bimonthly_diff.twitch_views", "bimonthly_diff.twitch_weekly_viewer_hours", "bimonthly_diff.ws_views", "bimonthly_diff.ycs_subscribers", "bimonthly_diff.ycs_views", "bimonthly_diff.youtube_daily_video_views", "bimonthly_diff.youtube_ed_playlist_count", "bimonthly_diff.youtube_ed_playlist_total_reach", "bimonthly_diff.youtube_monthly_video_views", "bimonthly_diff.youtube_playlist_count", "bimonthly_diff.youtube_playlist_total_reach", "bimonthly_diff.snap_subscribers", "bimonthly_diff.anghami_followers", "bimonthly_diff.anghami_plays", "bimonthly_diff_percent.amazon_ed_playlist_count", "bimonthly_diff_percent.amazon_playlist_count", "bimonthly_diff_percent.boomplay_comments", "bimonthly_diff_percent.boomplay_favorites", "bimonthly_diff_percent.boomplay_plays", "bimonthly_diff_percent.boomplay_ranking_current", "bimonthly_diff_percent.boomplay_shares", "bimonthly_diff_percent.bs_followers", "bimonthly_diff_percent.deezer_ed_playlist_count", "bimonthly_diff_percent.deezer_ed_playlist_total_reach", "bimonthly_diff_percent.deezer_fans", "bimonthly_diff_percent.deezer_playlist_count", "bimonthly_diff_percent.deezer_playlist_total_reach", "bimonthly_diff_percent.facebook_followers", "bimonthly_diff_percent.fs_likes", "bimonthly_diff_percent.fs_talks", "bimonthly_diff_percent.genius_pageviews", "bimonthly_diff_percent.ins_engagement_rate", "bimonthly_diff_percent.ins_followers", "bimonthly_diff_percent.itunes_ed_playlist_count", "bimonthly_diff_percent.itunes_playlist_count", "bimonthly_diff_percent.line_music_artist_likes", "bimonthly_diff_percent.line_music_likes", "bimonthly_diff_percent.line_music_mv_plays", "bimonthly_diff_percent.line_music_plays", "bimonthly_diff_percent.melon_artist_fans", "bimonthly_diff_percent.melon_likes", "bimonthly_diff_percent.melon_video_likes", "bimonthly_diff_percent.melon_video_views", "bimonthly_diff_percent.pandora_lifetime_stations_added", "bimonthly_diff_percent.pandora_lifetime_streams", "bimonthly_diff_percent.pandora_listeners_28_day", "bimonthly_diff_percent.shazam_count", "bimonthly_diff_percent.songkick_fans", "bimonthly_diff_percent.soundcloud_followers", "bimonthly_diff_percent.soundcloud_plays", "bimonthly_diff_percent.sp_followers", "bimonthly_diff_percent.sp_followers_to_listeners_ratio", "bimonthly_diff_percent.sp_listeners_to_followers_ratio", "bimonthly_diff_percent.sp_monthly_listeners", "bimonthly_diff_percent.sp_popularity", "bimonthly_diff_percent.spotify_ed_playlist_count", "bimonthly_diff_percent.spotify_ed_playlist_total_reach", "bimonthly_diff_percent.spotify_playlist_count", "bimonthly_diff_percent.spotify_playlist_total_reach", "bimonthly_diff_percent.tiktok_followers", "bimonthly_diff_percent.tiktok_likes", "bimonthly_diff_percent.tiktok_top_video_views", "bimonthly_diff_percent.tiktok_track_posts", "bimonthly_diff_percent.ts_followers", "bimonthly_diff_percent.ts_likes", "bimonthly_diff_percent.ts_tweet_count", "bimonthly_diff_percent.twitch_followers", "bimonthly_diff_percent.twitch_monthly_viewer_hours", "bimonthly_diff_percent.twitch_views", "bimonthly_diff_percent.twitch_weekly_viewer_hours", "bimonthly_diff_percent.ws_views", "bimonthly_diff_percent.ycs_subscribers", "bimonthly_diff_percent.ycs_views", "bimonthly_diff_percent.youtube_daily_video_views", "bimonthly_diff_percent.youtube_ed_playlist_count", "bimonthly_diff_percent.youtube_ed_playlist_total_reach", "bimonthly_diff_percent.youtube_monthly_video_views", "bimonthly_diff_percent.youtube_playlist_count", "bimonthly_diff_percent.youtube_playlist_total_reach", "bimonthly_diff_percent.snap_subscribers", "bimonthly_diff_percent.anghami_followers", "bimonthly_diff_percent.anghami_plays", "cm_artist_rank", "latest.rank", "rank_eg", "rank_fb" ], "description": "Sort column in `.` form. `[stat]` resolves to `latest.[stat]` when no period is provided.", "default": "latest.rank" }, "required": false, "description": "Sort column in `.` form. `[stat]` resolves to `latest.[stat]` when no period is provided." }, { "name": "sortOrderDesc", "in": "query", "schema": { "type": "boolean", "description": "If true (default), sort descending by `sortColumn`.", "default": true }, "required": false, "description": "If true (default), sort descending by `sortColumn`." }, { "name": "career_stage", "in": "query", "schema": { "type": "string", "enum": [ "undiscovered", "developing", "mid-level", "mainstream", "superstar", "legendary" ], "description": "Filter by career stage. One of `undiscovered`, `developing`, `mid-level`, `mainstream`, `superstar`, `legendary`." }, "required": false, "description": "Filter by career stage. One of `undiscovered`, `developing`, `mid-level`, `mainstream`, `superstar`, `legendary`." }, { "name": "career_stage_score[]", "in": "query", "schema": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 100, "title": "career_stage_score boundaries" }, "description": "2-item array `[min, max]` for career-stage score filter (each value 0..100)." }, "required": false, "description": "2-item array `[min, max]` for career-stage score filter (each value 0..100)." }, { "name": "career_trend", "in": "query", "schema": { "type": "string", "enum": [ "decline", "gradual decline", "steady", "growth", "explosive growth" ], "description": "Filter by recent-momentum trend category. One of `decline`, `gradual decline`, `steady`, `growth`, `explosive growth`." }, "required": false, "description": "Filter by recent-momentum trend category. One of `decline`, `gradual decline`, `steady`, `growth`, `explosive growth`." }, { "name": "career_trend_score[]", "in": "query", "schema": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 100, "title": "career_trend_score boundaries" }, "description": "2-item array `[min, max]` for career-trend score filter (each value 0..100)." }, "required": false, "description": "2-item array `[min, max]` for career-trend score filter (each value 0..100)." }, { "name": "shortlistIds[]", "in": "query", "schema": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "uniqueItems": true, "description": "Restrict to artists included on these Chartmetric user shortlists (array of shortlist IDs)." }, "required": false, "description": "Restrict to artists included on these Chartmetric user shortlists (array of shortlist IDs)." }, { "name": "sp_p[]", "in": "query", "schema": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 100 }, "description": "2-item array `[min, max]` filter on Spotify popularity (0–100)." }, "required": false, "description": "2-item array `[min, max]` filter on Spotify popularity (0–100)." }, { "name": "sp_f[]", "in": "query", "schema": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 200000000 }, "description": "2-item array `[min, max]` filter on Spotify followers." }, "required": false, "description": "2-item array `[min, max]` filter on Spotify followers." }, { "name": "dz_fans[]", "in": "query", "schema": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 50000000 }, "description": "2-item array `[min, max]` filter on Deezer fans." }, "required": false, "description": "2-item array `[min, max]` filter on Deezer fans." }, { "name": "sp_ml[]", "in": "query", "schema": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 500000000 }, "description": "2-item array `[min, max]` filter on Spotify monthly listeners." }, "required": false, "description": "2-item array `[min, max]` filter on Spotify monthly listeners." }, { "name": "sp_ratio[]", "in": "query", "schema": { "type": "array", "items": { "type": "number", "format": "float", "minimum": 0, "maximum": 18000000 }, "description": "2-item array `[min, max]` filter on Spotify listeners-to-followers ratio." }, "required": false, "description": "2-item array `[min, max]` filter on Spotify listeners-to-followers ratio." }, { "name": "sp_fl_ratio[]", "in": "query", "schema": { "type": "array", "items": { "type": "number", "format": "float", "minimum": 0, "maximum": 1000000 }, "description": "2-item array `[min, max]` filter on Spotify followers-to-listeners ratio." }, "required": false, "description": "2-item array `[min, max]` filter on Spotify followers-to-listeners ratio." }, { "name": "tt_f[]", "in": "query", "schema": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 200000000 }, "description": "2-item array `[min, max]` filter on TikTok followers." }, "required": false, "description": "2-item array `[min, max]` filter on TikTok followers." }, { "name": "tt_l[]", "in": "query", "schema": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 100000000000 }, "description": "2-item array `[min, max]` filter on TikTok likes." }, "required": false, "description": "2-item array `[min, max]` filter on TikTok likes." }, { "name": "fb_f[]", "in": "query", "schema": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 500000000 }, "description": "2-item array `[min, max]` filter on Facebook followers." }, "required": false, "description": "2-item array `[min, max]` filter on Facebook followers." }, { "name": "fb_l[]", "in": "query", "schema": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 200000000 }, "description": "2-item array `[min, max]` filter on Facebook likes." }, "required": false, "description": "2-item array `[min, max]` filter on Facebook likes." }, { "name": "fb_t[]", "in": "query", "schema": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 50000000 }, "description": "2-item array `[min, max]` filter on Facebook talks (people-talking-about)." }, "required": false, "description": "2-item array `[min, max]` filter on Facebook talks (people-talking-about)." }, { "name": "tw_f[]", "in": "query", "schema": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 500000000 }, "description": "2-item array `[min, max]` filter on Twitter/X followers." }, "required": false, "description": "2-item array `[min, max]` filter on Twitter/X followers." }, { "name": "tw_r[]", "in": "query", "schema": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 50000000 }, "description": "2-item array `[min, max]` filter on Twitter/X retweets." }, "required": false, "description": "2-item array `[min, max]` filter on Twitter/X retweets." }, { "name": "ig_f[]", "in": "query", "schema": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 500000000 }, "description": "2-item array `[min, max]` filter on Instagram followers." }, "required": false, "description": "2-item array `[min, max]` filter on Instagram followers." }, { "name": "ytc_v[]", "in": "query", "schema": { "type": "array", "items": { "type": "number", "format": "float", "minimum": 0, "maximum": 500000000000 }, "description": "2-item array `[min, max]` filter on YouTube channel views." }, "required": false, "description": "2-item array `[min, max]` filter on YouTube channel views." }, { "name": "ytc_s[]", "in": "query", "schema": { "type": "array", "items": { "type": "number", "format": "float", "minimum": 0, "maximum": 200000000 }, "description": "2-item array `[min, max]` filter on YouTube channel subscribers." }, "required": false, "description": "2-item array `[min, max]` filter on YouTube channel subscribers." }, { "name": "ytd_vv[]", "in": "query", "schema": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 150000000 }, "description": "2-item array `[min, max]` filter on YouTube daily video views." }, "required": false, "description": "2-item array `[min, max]` filter on YouTube daily video views." }, { "name": "ytm_vv[]", "in": "query", "schema": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 2000000000 }, "description": "2-item array `[min, max]` filter on YouTube monthly video views." }, "required": false, "description": "2-item array `[min, max]` filter on YouTube monthly video views." }, { "name": "wp_v[]", "in": "query", "schema": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 200000000 }, "description": "2-item array `[min, max]` filter on Wikipedia views." }, "required": false, "description": "2-item array `[min, max]` filter on Wikipedia views." }, { "name": "sc_f[]", "in": "query", "schema": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 200000000 }, "description": "2-item array `[min, max]` filter on SoundCloud followers." }, "required": false, "description": "2-item array `[min, max]` filter on SoundCloud followers." }, { "name": "bit_f[]", "in": "query", "schema": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 50000000 }, "description": "2-item array `[min, max]` filter on Bandsintown followers." }, "required": false, "description": "2-item array `[min, max]` filter on Bandsintown followers." }, { "name": "cpp[]", "in": "query", "schema": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 1000000 }, "description": "2-item array `[min, max]` filter on Chartmetric Cross-Platform Performance (CPP) rank." }, "required": false, "description": "2-item array `[min, max]` filter on Chartmetric Cross-Platform Performance (CPP) rank." }, { "name": "score[]", "in": "query", "schema": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 600000 }, "description": "2-item array `[min, max]` filter on Chartmetric artist score." }, "required": false, "description": "2-item array `[min, max]` filter on Chartmetric artist score." }, { "name": "t_f[]", "in": "query", "schema": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 10000000 }, "description": "2-item array `[min, max]` filter on Twitch followers." }, "required": false, "description": "2-item array `[min, max]` filter on Twitch followers." }, { "name": "t_v[]", "in": "query", "schema": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 500000000 }, "description": "2-item array `[min, max]` filter on Twitch views." }, "required": false, "description": "2-item array `[min, max]` filter on Twitch views." }, { "name": "t_mvh[]", "in": "query", "schema": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 2000000 }, "description": "2-item array `[min, max]` filter on Twitch monthly viewer hours." }, "required": false, "description": "2-item array `[min, max]` filter on Twitch monthly viewer hours." }, { "name": "t_wvh[]", "in": "query", "schema": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 1000000 }, "description": "2-item array `[min, max]` filter on Twitch weekly viewer hours." }, "required": false, "description": "2-item array `[min, max]` filter on Twitch weekly viewer hours." }, { "name": "p_ml[]", "in": "query", "schema": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 100000000 }, "description": "2-item array `[min, max]` filter on Pandora 28-day listeners." }, "required": false, "description": "2-item array `[min, max]` filter on Pandora 28-day listeners." }, { "name": "p_s[]", "in": "query", "schema": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 50000 }, "description": "2-item array `[min, max]` filter on Pandora stations added." }, "required": false, "description": "2-item array `[min, max]` filter on Pandora stations added." }, { "name": "p_ls[]", "in": "query", "schema": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 200000000 }, "description": "2-item array `[min, max]` filter on Pandora lifetime stations added." }, "required": false, "description": "2-item array `[min, max]` filter on Pandora lifetime stations added." }, { "name": "p_lsr[]", "in": "query", "schema": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 100000000000 }, "description": "2-item array `[min, max]` filter on Pandora lifetime streams." }, "required": false, "description": "2-item array `[min, max]` filter on Pandora lifetime streams." }, { "name": "bp_c[]", "in": "query", "schema": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 100000 }, "description": "2-item array `[min, max]` filter on Boomplay comments." }, "required": false, "description": "2-item array `[min, max]` filter on Boomplay comments." }, { "name": "bp_f[]", "in": "query", "schema": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 100000 }, "description": "2-item array `[min, max]` filter on Boomplay favorites." }, "required": false, "description": "2-item array `[min, max]` filter on Boomplay favorites." }, { "name": "bp_p[]", "in": "query", "schema": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 200000000 }, "description": "2-item array `[min, max]` filter on Boomplay plays." }, "required": false, "description": "2-item array `[min, max]` filter on Boomplay plays." }, { "name": "bp_s[]", "in": "query", "schema": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 100000 }, "description": "2-item array `[min, max]` filter on Boomplay shares." }, "required": false, "description": "2-item array `[min, max]` filter on Boomplay shares." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "object", "properties": { "obj": { "type": "array", "items": { "type": "object", "properties": { "cm_artist": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 2147483647 }, { "type": "string" } ], "nullable": true, "description": "Chartmetric artist ID. May arrive as string from ES." }, "name": { "type": [ "string", "null" ], "description": "Artist name." }, "pronoun": { "type": [ "string", "null" ], "description": "Artist's pronouns." }, "band": { "type": [ "boolean", "null" ], "description": "True when the profile represents a band, false for a solo artist." }, "image_url": { "type": [ "string", "null" ], "description": "Artist image URL." }, "code2": { "type": [ "string", "null" ], "description": "Artist country (ISO 3166-1 alpha-2)." }, "hometown_city": { "type": [ "string", "null" ], "description": "Artist's hometown city name." }, "current_city": { "type": [ "string", "null" ], "description": "Artist's current city name." }, "cm_tag": { "type": [ "array", "null" ], "items": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "description": "List of Chartmetric genre IDs." }, "genres": { "anyOf": [ { "type": "string" }, { "type": "array", "items": {} } ], "nullable": true, "description": "Genre names — may be a comma-joined string or an array depending on the source." }, "genre_smart_ordered": { "type": [ "array", "null" ], "items": { "type": "object", "properties": {} }, "description": "List of single-key objects mapping order index to genre ID, ordered by relevance." }, "career_status": { "type": [ "object", "null" ], "properties": { "stage": { "type": [ "string", "null" ], "description": "Artist's current career stage." }, "stage_score": { "type": [ "number", "null" ], "format": "float", "description": "Score (0–100) within the current `stage`." }, "trend": { "type": [ "string", "null" ], "description": "Artist's current career-trend category." }, "trend_score": { "type": [ "number", "null" ], "format": "float", "description": "Score (0–100) within the current `trend`." } }, "description": "Career stage and trend rollup as shown on the dashboard." }, "sp_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Spotify follower count." }, "sp_monthly_listeners": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Spotify monthly listener count." }, "sp_popularity": { "type": [ "number", "null" ], "format": "float", "description": "Spotify popularity score (0–100)." }, "sp_listeners_to_followers_ratio": { "type": [ "number", "null" ], "format": "float", "description": "Ratio of Spotify monthly listeners to Spotify followers." }, "sp_followers_to_listeners_ratio": { "type": [ "number", "null" ], "format": "float", "description": "Ratio of Spotify followers to Spotify monthly listeners." }, "deezer_fans": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Deezer fan count." }, "fs_likes": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Facebook page-like count." }, "fs_talks": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Facebook people-talking-about count: users discussing or interacting with the page." }, "ins_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Instagram follower count." }, "ts_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Twitter/X follower count." }, "ts_retweets": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Twitter/X retweet count." }, "ycs_views": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "YouTube channel total view count." }, "ycs_subscribers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "YouTube channel subscriber count." }, "youtube_daily_video_views": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "YouTube daily video view count." }, "youtube_monthly_video_views": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "YouTube monthly video view count." }, "ws_views": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Wikipedia page-view count." }, "soundcloud_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "SoundCloud follower count." }, "bs_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Bandsintown follower count." }, "tiktok_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "TikTok follower count." }, "tiktok_likes": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "TikTok total like count." }, "cm_artist_rank": { "type": [ "integer", "null" ], "description": "Chartmetric overall artist rank." }, "rank_fb": { "type": [ "integer", "null" ], "description": "Chartmetric fan-base rank." }, "rank_eg": { "type": [ "integer", "null" ], "description": "Chartmetric engagement rank." } } }, "description": "List of artists matching the filters." }, "offset": { "type": "integer", "minimum": 0, "description": "Pagination offset of the current result page." }, "total": { "type": "integer", "minimum": 0, "description": "Total number of artists matching the filters across all pages." } }, "required": [ "obj", "offset", "total" ] } }, "additionalProperties": false }, "examples": { "default": { "value": { "obj": { "obj": [ { "cm_artist": 3852, "name": "The Weeknd", "pronoun": "he/him", "band": false, "image_url": "https://i.scdn.co/image/ab6761610000e5eb214f3cf1cbe7139c1e26ffbb", "code2": "CA", "cm_tag": [ 462882, 462889, 462887 ], "career_status": { "stage": "superstar", "stage_score": 81, "trend": "steady", "trend_score": 48 }, "cm_artist_rank": 3, "rank_eg": 4, "rank_fb": 8, "sp_followers": 90205700, "sp_popularity": 94, "sp_monthly_listeners": 104636584, "ins_followers": 75278195, "ycs_subscribers": 35900000, "tiktok_followers": 9600000 } ], "offset": 10, "total": 49 } } } } } } } } } }, "/api/artist/{id}": { "get": { "summary": "Artist Metadata", "tags": [ "Artist" ], "operationId": "getArtistById", "description": "Artist metadata and Chartmetric stats by Chartmetric ID. `cm_statistics` carries a per-platform counter + rank map (Spotify, Apple Music, Deezer, Amazon, YouTube, TikTok, Twitter, Instagram, Pandora, Twitch, Line, Boomplay, Shazam, Genius). Pass header `x-accept-partial-data: true` to unblock responses while the artist's ES cache is being rebuilt.", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer", "minimum": 2, "maximum": 2147483647, "not": { "enum": [ 1 ] }, "description": "Chartmetric artist ID. Note: id=1 ('Various Artists') is rejected." }, "required": true, "description": "Chartmetric artist ID. Note: id=1 ('Various Artists') is rejected.", "examples": { "default": { "value": 2 } } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Chartmetric artist ID." }, "name": { "type": [ "string", "null" ], "description": "Artist name." }, "local_name": { "type": [ "string", "null" ], "description": "Localized artist name, when available." }, "local_name_locale": { "type": [ "string", "null" ], "description": "Locale for local_name, when available." }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Date the artist record was created in Chartmetric (ISO 8601)." }, "code2": { "type": [ "string", "null" ], "description": "Artist country (ISO 3166-1 alpha-2)." }, "band": { "type": [ "boolean", "null" ], "description": "True when the profile represents a band, false for a solo artist." }, "pronoun_title": { "type": [ "string", "null" ], "description": "Artist's pronouns (e.g. `she/her`, `they/them`)." }, "gender_title": { "type": [ "string", "null" ], "description": "Artist's gender label." }, "gender": { "type": [ "string", "null" ], "description": "Artist's gender code." }, "isni": { "type": [ "string", "null" ], "description": "International Standard Name Identifier (ISNI)." }, "cm_artist_rank": { "type": [ "integer", "null" ], "description": "Chartmetric overall artist rank." }, "cm_artist_score": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric artist score (0–100)." }, "cover_url": { "type": [ "string", "null" ], "description": "Artist cover (banner) image URL." }, "image_url": { "type": [ "string", "null" ], "description": "Artist profile image URL." }, "hometown_city": { "type": [ "string", "null" ], "description": "Artist's hometown city name." }, "current_city": { "type": [ "string", "null" ], "description": "Artist's current city name." }, "current_city_id": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Chartmetric ID of the artist's current city." }, "band_members": { "description": "Band-member metadata (shape varies)." }, "booking_agent": { "type": [ "string", "null" ], "description": "Booking agent name." }, "record_label": { "type": [ "string", "null" ], "description": "Record label name." }, "press_contact": { "type": [ "string", "null" ], "description": "Press contact details." }, "general_manager": { "type": [ "string", "null" ], "description": "General manager name." }, "topSongwriterCollaborators": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "List of frequent songwriter collaborator names." }, "description": { "type": [ "string", "null" ], "description": "Artist biography / description." }, "genres": { "type": [ "object", "null" ], "properties": { "primary": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Chartmetric genre ID." }, "name": { "type": [ "string", "null" ], "description": "Genre name." }, "type": { "type": [ "string", "null" ], "description": "Genre taxonomy version (e.g. `genre`, `genre_v2`). Internal field." }, "source": { "type": [ "string", "null" ], "description": "Genre attribution source (e.g. `cm`, `spotify`)." }, "score": { "type": [ "number", "null" ], "format": "float", "description": "Internal genre relevance score." } }, "description": "Artist's primary genre." }, "secondary": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Chartmetric genre ID." }, "name": { "type": [ "string", "null" ], "description": "Genre name." }, "type": { "type": [ "string", "null" ], "description": "Genre taxonomy version (e.g. `genre`, `genre_v2`). Internal field." }, "source": { "type": [ "string", "null" ], "description": "Genre attribution source (e.g. `cm`, `spotify`)." }, "score": { "type": [ "number", "null" ], "format": "float", "description": "Internal genre relevance score." } } }, "description": "List of artist's secondary genres." }, "sub": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Chartmetric genre ID." }, "name": { "type": [ "string", "null" ], "description": "Genre name." }, "type": { "type": [ "string", "null" ], "description": "Genre taxonomy version (e.g. `genre`, `genre_v2`). Internal field." }, "source": { "type": [ "string", "null" ], "description": "Genre attribution source (e.g. `cm`, `spotify`)." }, "score": { "type": [ "number", "null" ], "format": "float", "description": "Internal genre relevance score." } } }, "description": "List of artist sub-genres (Spotify-style detailed genres)." } }, "description": "Genre attribution by tier (primary, secondary, sub)." }, "genre_smart_ordered": { "type": [ "array", "null" ], "items": { "type": "object", "properties": {} }, "description": "List of single-key objects mapping order index to genre ID, ordered by relevance." }, "moods": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Chartmetric mood ID." }, "name": { "type": [ "string", "null" ], "description": "Mood label (e.g. `energetic`, `celebratory`)." } } }, "description": "List of moods associated with the artist's catalog." }, "activities": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Chartmetric activity ID." }, "name": { "type": [ "string", "null" ], "description": "Activity label (e.g. `partying`, `working out`)." } } }, "description": "List of listening activities associated with the artist." }, "career_status": { "type": [ "object", "null" ], "properties": { "stage": { "type": [ "string", "null" ], "description": "Artist's current career stage. Values in order: `undiscovered`, `developing`, `mid-level`, `mainstream`, `superstar`, `legendary`." }, "stage_score": { "type": [ "number", "null" ], "format": "float", "description": "Score (0–100) representing relative progression through the current `stage`." }, "trend": { "type": [ "string", "null" ], "description": "Artist's recent career trend. Values in order: `decline`, `gradual decline`, `steady`, `growth`, `explosive growth`." }, "trend_score": { "type": [ "number", "null" ], "format": "float", "description": "Score (0–100) representing relative strength within the current `trend`." } }, "description": "Career stage and trend rollup as shown on the dashboard." }, "cm_statistics": { "type": [ "object", "null" ], "properties": { "sp_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Spotify follower count." }, "sp_monthly_listeners": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Spotify monthly listener count." }, "sp_popularity": { "type": [ "number", "null" ], "format": "float", "description": "Spotify popularity score (0–100)." }, "sp_listeners_to_followers_ratio": { "type": [ "number", "null" ], "format": "float", "description": "Ratio of Spotify monthly listeners to Spotify followers." }, "sp_followers_to_listeners_ratio": { "type": [ "number", "null" ], "format": "float", "description": "Ratio of Spotify followers to Spotify monthly listeners." }, "deezer_fans": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Deezer fan count." }, "fs_likes": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Facebook page-like count." }, "fs_talks": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Facebook people-talking-about count: users discussing or interacting with the page." }, "ins_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Instagram follower count." }, "ts_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Twitter/X follower count." }, "ts_retweets": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Twitter/X retweet count." }, "ycs_views": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "YouTube channel total view count." }, "ycs_subscribers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "YouTube channel subscriber count." }, "youtube_daily_video_views": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "YouTube daily video view count." }, "youtube_monthly_video_views": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "YouTube monthly video view count." }, "ws_views": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Wikipedia page-view count." }, "soundcloud_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "SoundCloud follower count." }, "bs_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Bandsintown follower count." }, "tiktok_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "TikTok follower count." }, "tiktok_likes": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "TikTok total like count." }, "cm_artist_rank": { "type": [ "number", "null" ], "format": "float", "description": "Global Chartmetric artist rank (1 is highest)." }, "sp_followers_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Spotify followers." }, "sp_popularity_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Spotify popularity." }, "sp_monthly_listeners_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Spotify monthly listeners." }, "sp_where_people_listen": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "code2": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-2 country code of the listener location." }, "listeners": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Spotify monthly listener count for this location. May arrive as string (uncast aggregate)." }, "name": { "type": [ "string", "null" ], "description": "City or country name of the listener location." } } }, "description": "Top Spotify listener locations (countries/cities)." }, "deezer_fans_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Deezer fans." }, "ins_followers_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Instagram followers." }, "ycs_subscribers_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by YouTube channel subscribers." }, "ycs_views_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by YouTube channel views." }, "tiktok_followers_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by TikTok followers." }, "tiktok_likes_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by TikTok likes." }, "tiktok_top_video_views": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Top TikTok video view count." }, "tiktok_top_video_views_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by top TikTok video views." }, "tiktok_top_video_comments": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Top TikTok video comment count." }, "tiktok_top_video_comments_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by top TikTok video comments." }, "tiktok_track_posts": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Total TikTok posts using the artist’s tracks." }, "tiktok_track_posts_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by TikTok track posts." }, "twitter_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Twitter follower count." }, "twitter_followers_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Twitter followers." }, "line_music_artist_likes": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Line Music artist like count." }, "line_music_artist_likes_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Line Music artist likes." }, "line_music_likes": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Line Music track-likes total." }, "line_music_likes_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Line Music likes." }, "line_music_plays": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Line Music play count." }, "line_music_plays_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Line Music plays." }, "line_music_mv_plays": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Line Music music-video play count." }, "fan_base_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric fan-base composite rank." }, "engagement_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric engagement composite rank." }, "youtube_daily_video_views_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by YouTube daily video views." }, "youtube_monthly_video_views_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by YouTube monthly video views." }, "twitch_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Twitch follower count." }, "twitch_followers_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Twitch followers." }, "twitch_views": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Twitch total view count." }, "twitch_views_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Twitch views." }, "twitch_monthly_viewer_hours": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Twitch monthly viewer-hours." }, "twitch_monthly_viewer_hours_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Twitch monthly viewer-hours." }, "twitch_weekly_viewer_hours": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Twitch weekly viewer-hours." }, "twitch_weekly_viewer_hours_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Twitch weekly viewer-hours." }, "pandora_listeners_28_day": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Pandora 28-day listener count." }, "pandora_listeners_28_day_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Pandora 28-day listeners." }, "pandora_lifetime_stations_added": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Pandora lifetime stations-added count." }, "pandora_lifetime_stations_added_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Pandora lifetime stations added." }, "pandora_lifetime_streams": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Pandora lifetime stream count." }, "pandora_lifetime_streams_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Pandora lifetime streams." }, "boomplay_ranking_current": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Current Boomplay ranking." }, "boomplay_ranking_current_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by current Boomplay ranking." }, "boomplay_favorites": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Boomplay favorite count." }, "boomplay_favorites_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Boomplay favorites." }, "boomplay_shares": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Boomplay share count." }, "boomplay_shares_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Boomplay shares." }, "boomplay_comments": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Boomplay comment count." }, "boomplay_comments_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Boomplay comments." }, "boomplay_plays": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Boomplay play count." }, "boomplay_plays_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Boomplay plays." }, "num_sp_editorial_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of Spotify editorial playlists featuring this artist." }, "num_sp_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of Spotify playlists featuring this artist." }, "sp_playlist_total_reach": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Sum of followers from all Spotify playlists featuring this artist." }, "sp_editorial_playlist_total_reach": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Sum of followers from all Spotify editorial playlists featuring this artist." }, "num_am_editorial_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of Apple Music editorial playlists featuring this artist." }, "num_am_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of Apple Music playlists featuring this artist." }, "num_de_editorial_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of Deezer editorial playlists featuring this artist." }, "num_de_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of Deezer playlists featuring this artist." }, "de_playlist_total_reach": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Sum of fans from all Deezer playlists featuring this artist." }, "de_editorial_playlist_total_reach": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Sum of fans from all Deezer editorial playlists featuring this artist." }, "num_az_editorial_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of Amazon editorial playlists featuring this artist." }, "num_az_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of Amazon playlists featuring this artist." }, "num_yt_editorial_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of YouTube editorial playlists featuring this artist." }, "num_yt_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of YouTube playlists featuring this artist." }, "yt_playlist_total_reach": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Sum of views from all YouTube playlists featuring this artist." }, "yt_editorial_playlist_total_reach": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Sum of views from all YouTube editorial playlists featuring this artist." }, "shazam_count": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Sum of Shazam plays across the artist's tracks." }, "genius_pageviews": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Total Genius page-view count for the artist." }, "genreRank": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ], "description": "Name of the top genre." }, "rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank within the top genre." } } }, "subGenreRank1": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ], "description": "Name of the first top sub-genre." }, "rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank within the first top sub-genre." } } }, "subGenreRank2": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ], "description": "Name of the second top sub-genre." }, "rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank within the second top sub-genre." } } }, "countryRank": { "type": [ "object", "null" ], "properties": { "country": { "type": [ "string", "null" ], "description": "Country name." }, "rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank within the country." } }, "description": "Artist's rank within their primary country." } }, "description": "Permissive map of per-platform counters and ranks across major streaming, social, and chart platforms. Sparsely populated based on artist platform presence." }, "genreRank": { "type": [ "object", "null" ], "properties": {}, "description": "Artist's top-genre ranking stats (e.g. `{ name, rank }`)." }, "subGenreRank1": { "type": [ "object", "null" ], "properties": {}, "description": "Artist's first top sub-genre ranking stats." }, "subGenreRank2": { "type": [ "object", "null" ], "properties": {}, "description": "Artist's second top sub-genre ranking stats." } } } }, "additionalProperties": false }, "examples": { "default": { "value": { "obj": { "id": 2000, "name": "Nina Sky", "local_name": null, "local_name_locale": null, "created_at": "2025-10-30T15:45:02Z", "code2": "US", "band": true, "pronoun_title": "they/them", "gender_title": null, "gender": null, "isni": "0000000109438445", "cm_artist_rank": 4505, "cm_artist_score": 86.15, "cover_url": "https://is1-ssl.mzstatic.com/image/thumb/Music211/v4/37/a9/c6/37a9c658-8dbc-1d35-881c-afe798f96943/413b2199-8d1b-433e-9224-b2e175a8ea37.png/160x160bb.jpg", "image_url": "https://i.scdn.co/image/ab6761610000e5eb99130a511f82caacd3fecc03", "hometown_city": "Queens", "current_city": null, "current_city_id": null, "band_members": null, "booking_agent": null, "record_label": "Glossy Vinyl", "press_contact": null, "general_manager": null, "topSongwriterCollaborators": [ "Lionel Bermingham" ], "description": "Born and raised in New York City, twin sisters Nicole and Natalie Albino...", "genres": { "primary": { "id": 501120, "name": "pop", "type": "genre_v2", "source": "cm" }, "secondary": [ { "id": 501125, "name": "r&b/soul", "type": "genre_v2", "source": "cm" }, { "id": 501146, "name": "dance", "type": "genre_v2", "source": "cm" } ], "sub": [ { "id": 9122, "name": "hip pop", "type": "genre", "source": "spotify" } ] }, "genre_smart_ordered": [ { "1": 501120 }, { "2": 501125 } ], "moods": [ { "id": 504927, "name": "celebratory" }, { "id": 504954, "name": "energetic" } ], "activities": [ { "id": 504872, "name": "dancy" }, { "id": 504876, "name": "partying" } ], "career_status": { "stage": "mainstream", "stage_score": 42, "trend": "decline", "trend_score": 96 }, "cm_statistics": { "countryRank": { "code2": "US", "country": "United States", "rank": 1, "percentile": 1 }, "sp_followers": 147460505, "sp_followers_rank": 2, "sp_popularity": 100, "sp_popularity_rank": 1, "sp_monthly_listeners": 106103812, "sp_monthly_listeners_rank": 5, "sp_where_people_listen": [ { "code2": "id", "listeners": 2465588, "name": "Jakarta" }, { "code2": "gb", "listeners": 2152620, "name": "London" } ], "cm_artist_rank": 1, "fan_base_rank": 1, "engagement_rank": 1, "shazam_count": 244928447, "genius_pageviews": 198089148 }, "genreRank": { "name": "pop", "rank": 1 }, "subGenreRank1": { "name": "r&b/soul", "rank": 1 }, "subGenreRank2": { "name": "dance", "rank": 1 } } } } } } } } } } }, "/api/artist/{id}/relatedartists": { "get": { "summary": "Related Artists", "tags": [ "Artist" ], "operationId": "listArtistRelatedArtists", "description": "Related artists (\"fans also listen to\") for the given Chartmetric artist. Base response returns only metadata + `cm_artist_score`; pass `fromDaysAgo` + `toDaysAgo` to additionally hydrate per-artist `preview_url`, `preview_track_id`, `rank_stats` (array of `{rank, timestp}` over the requested date range), `rank_diff`, and `genres`. Apidoc types `rank_stats` as a single object — in reality it's an array from `getRankStatBatch`.", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer", "minimum": 2, "maximum": 2147483647, "not": { "enum": [ 1 ] }, "description": "Chartmetric artist ID. Note: id=1 ('Various Artists') is rejected." }, "required": true, "description": "Chartmetric artist ID. Note: id=1 ('Various Artists') is rejected.", "examples": { "default": { "value": 2 } } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 50, "description": "Maximum number of related artists to return. Defaults to 10, max 50.", "default": 10 }, "required": true, "description": "Maximum number of related artists to return. Defaults to 10, max 50.", "examples": { "default": { "value": 10 } } }, { "name": "fromDaysAgo", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Start of a date range in days ago from today. When set with `toDaysAgo`, returns extra per-artist enrichments (`preview_url`, `preview_track_id`, `rank_stats`, `rank_diff`, `genres`)." }, "required": false, "description": "Start of a date range in days ago from today. When set with `toDaysAgo`, returns extra per-artist enrichments (`preview_url`, `preview_track_id`, `rank_stats`, `rank_diff`, `genres`)." }, { "name": "toDaysAgo", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Optional end of a date range in days ago from today. Defaults to 0 (today). When set together with `fromDaysAgo`, additional per-artist enrichments are returned." }, "required": false, "description": "Optional end of a date range in days ago from today. Defaults to 0 (today). When set together with `fromDaysAgo`, additional per-artist enrichments are returned." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Chartmetric artist ID of the related artist." }, "name": { "type": [ "string", "null" ], "description": "Related artist name." }, "code2": { "type": [ "string", "null" ], "description": "Related artist country (ISO 3166-1 alpha-2)." }, "cm_artist_rank": { "type": [ "integer", "null" ], "description": "Related artist's Chartmetric rank." }, "cm_artist_score": { "type": [ "number", "null" ], "format": "float", "description": "Related artist's Chartmetric score (0–100)." }, "image_url": { "type": [ "string", "null" ], "description": "Related artist image URL." }, "sp_followers": { "type": [ "integer", "null" ], "minimum": 0, "description": "Spotify follower count." }, "popularity": { "type": [ "integer", "null" ], "description": "Spotify popularity score (0–100)." }, "rank_diff": { "type": [ "integer", "null" ], "description": "Change in `cm_artist_rank` between the `toDaysAgo` date and the previous date." }, "preview_url": { "type": [ "string", "null" ], "description": "Preview audio URL (only present when date range provided)." }, "preview_track_id": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 2147483647 }, { "type": "string" } ], "nullable": true, "description": "Chartmetric ID of the preview track." }, "genres": { "type": [ "object", "null" ], "properties": { "primary": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Chartmetric genre ID." }, "name": { "type": [ "string", "null" ], "description": "Genre name." }, "link_type": { "type": [ "string", "null" ], "description": "Genre link type (e.g. `cm_artist_genre`, `cm_artist_sub_genre`)." }, "score": { "type": [ "number", "null" ], "format": "float", "description": "Internal genre relevance score." } }, "description": "Related artist's primary genre." }, "secondary": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Chartmetric genre ID." }, "name": { "type": [ "string", "null" ], "description": "Genre name." }, "link_type": { "type": [ "string", "null" ], "description": "Genre link type (e.g. `cm_artist_genre`, `cm_artist_sub_genre`)." }, "score": { "type": [ "number", "null" ], "format": "float", "description": "Internal genre relevance score." } } }, "description": "List of related artist's secondary genres." }, "sub": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Chartmetric genre ID." }, "name": { "type": [ "string", "null" ], "description": "Genre name." }, "link_type": { "type": [ "string", "null" ], "description": "Genre link type (e.g. `cm_artist_genre`, `cm_artist_sub_genre`)." }, "score": { "type": [ "number", "null" ], "format": "float", "description": "Internal genre relevance score." } } }, "description": "List of related artist's sub-genres." } }, "description": "Genre attribution for the related artist." }, "rank_stats": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "rank": { "type": [ "integer", "null" ], "description": "Chartmetric artist rank on this date." }, "timestp": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Date of the rank stat (ISO 8601)." } } } }, { "type": "object", "properties": {} } ], "nullable": true, "description": "Historical rank time-series across the requested window. Array of `{rank, timestp}` rows." } } } } }, "required": [ "obj" ], "additionalProperties": false }, "examples": { "default": { "value": { "obj": [ { "id": 113381, "name": "Ozuna", "code2": "pr", "cm_artist_rank": 52, "cm_artist_score": 85.4, "image_url": "https://i.scdn.co/image/ab67616100005174b34caaa3f41eaf9ff5fe849d", "sp_followers": 32851167, "popularity": 85, "rank_diff": 0, "genres": { "primary": { "id": 462958, "name": "Latin Hip-Hop/Rap", "link_type": "cm_artist_genre", "score": 5 }, "secondary": [ { "id": 462957, "name": "Latin Pop", "link_type": "cm_artist_genre", "score": 4 }, { "id": 462896, "name": "Reggae", "link_type": "cm_artist_genre", "score": 2 } ], "sub": [ { "id": 402145, "name": "trap latino", "link_type": "cm_artist_sub_genre", "score": 0 } ] }, "rank_stats": [ { "rank": 52, "timestp": "2022-07-29" }, { "rank": 52, "timestp": "2022-07-28" } ] } ] } } } } } } } } }, "/api/artist/{id}/where-people-listen": { "get": { "summary": "💎 Premium — Spotify Monthly Listeners by City / Country", "tags": [ "Artist" ], "operationId": "getArtistWherePeopleListen", "description": "Spotify \"Where people listen\" snapshots for the artist — listener counts keyed by city / country name with historical time-series or latest snapshot. Pass `latest=true` (or a specific `date`) to receive snapshot form; omit both for a time-series between `since` / `until`. Spotify data for top 50 cities is real prior to Aug 12, 2024; after that date the platform only provides estimates and missing days are filled by the Chartmetric model (`is_estimate: true`).", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer", "minimum": 2, "maximum": 2147483647, "not": { "enum": [ 1 ] }, "description": "Chartmetric artist ID. Note: id=1 ('Various Artists') is rejected." }, "required": true, "description": "Chartmetric artist ID. Note: id=1 ('Various Artists') is rejected.", "examples": { "default": { "value": 2 } } }, { "name": "since", "in": "query", "schema": { "type": "string", "format": "date", "description": "Start of the date window in ISO format (e.g. '2025-11-01'). Defaults to 180 days ago. Ignored when `latest=true` or `date` is supplied.", "default": "2026-05-09" }, "required": false, "description": "Start of the date window in ISO format (e.g. '2025-11-01'). Defaults to 180 days ago. Ignored when `latest=true` or `date` is supplied." }, { "name": "until", "in": "query", "schema": { "type": "string", "format": "date", "description": "End of the date window in ISO format (e.g. '2025-11-15'). Defaults to today. Ignored when `latest=true` or `date` is supplied.", "default": "2026-11-05" }, "required": false, "description": "End of the date window in ISO format (e.g. '2025-11-15'). Defaults to today. Ignored when `latest=true` or `date` is supplied." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Number of locations to skip from the start of the result set, applied to cities and countries independently." }, "required": false, "description": "Number of locations to skip from the start of the result set, applied to cities and countries independently." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 50, "description": "Maximum number of locations to return, applied to cities and countries independently. Defaults to 10, max 50.", "default": 10 }, "required": false, "description": "Maximum number of locations to return, applied to cities and countries independently. Defaults to 10, max 50." }, { "name": "latest", "in": "query", "schema": { "type": "boolean", "description": "If true, returns only the most recent snapshot and ignores `since`/`until`." }, "required": false, "description": "If true, returns only the most recent snapshot and ignores `since`/`until`." }, { "name": "date", "in": "query", "schema": { "type": "string", "format": "date", "description": "Single-date snapshot in ISO format (YYYY-MM-DD). When set, returns one snapshot for that date and `since`/`until` are ignored." }, "required": false, "description": "Single-date snapshot in ISO format (YYYY-MM-DD). When set, returns one snapshot for that date and `since`/`until` are ignored." }, { "name": "includeEstimates", "in": "query", "schema": { "type": "boolean", "description": "If true (default), include Chartmetric-estimated city/country listener counts where Spotify no longer publishes real values (post 2024-08-12). Set to false to return only confirmed source data.", "default": true }, "required": false, "description": "If true (default), include Chartmetric-estimated city/country listener counts where Spotify no longer publishes real values (post 2024-08-12). Set to false to return only confirmed source data." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "object", "properties": { "cities": { "type": "object", "properties": {}, "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "timestp": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Snapshot timestamp (ISO 8601)." }, "code2": { "type": [ "string", "null" ], "description": "Country code of the location (ISO 3166-1 alpha-2)." }, "spotify_artist_id": { "type": [ "string", "null" ], "description": "Spotify artist ID for the artist." }, "lat": { "type": [ "number", "null" ], "format": "float", "description": "Latitude of the location." }, "lng": { "type": [ "number", "null" ], "format": "float", "description": "Longitude of the location." }, "region": { "type": [ "string", "null" ], "description": "Location region — `CITY` or `COUNTRY`." }, "city_id": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Chartmetric city ID." }, "spotify_artist_insights_location": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Internal Spotify artist-insights location identifier." }, "current_max_count": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Maximum listener count at this location across all artists. May arrive as string." }, "market_max_cm_artist_id": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Chartmetric artist ID of the artist with the most listeners at this location." }, "market_max_artist_name": { "type": [ "string", "null" ], "description": "Name of the artist with the most listeners at this location." }, "listeners": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Current listener count for this artist at this location." }, "prev_listeners": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Listener count from the previous snapshot." }, "artist_city_rank": { "type": [ "integer", "null" ], "description": "Artist's rank within this location." }, "max_listeners": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Maximum listener count for this artist across all snapshots." }, "population": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Population of the city or country." }, "city_affinity": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Artist's affinity score for the city." }, "is_estimate": { "type": [ "boolean", "null" ], "description": "True when the listener count is a Chartmetric estimate (post 2024-08-12 Spotify shift to estimates only)." } } } }, "description": "Map of city name → list of listener-count snapshots." }, "countries": { "type": "object", "properties": {}, "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "timestp": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Snapshot timestamp (ISO 8601)." }, "code2": { "type": [ "string", "null" ], "description": "Country code of the location (ISO 3166-1 alpha-2)." }, "spotify_artist_id": { "type": [ "string", "null" ], "description": "Spotify artist ID for the artist." }, "lat": { "type": [ "number", "null" ], "format": "float", "description": "Latitude of the location." }, "lng": { "type": [ "number", "null" ], "format": "float", "description": "Longitude of the location." }, "region": { "type": [ "string", "null" ], "description": "Location region — `CITY` or `COUNTRY`." }, "city_id": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Chartmetric city ID." }, "spotify_artist_insights_location": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Internal Spotify artist-insights location identifier." }, "current_max_count": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Maximum listener count at this location across all artists. May arrive as string." }, "market_max_cm_artist_id": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Chartmetric artist ID of the artist with the most listeners at this location." }, "market_max_artist_name": { "type": [ "string", "null" ], "description": "Name of the artist with the most listeners at this location." }, "listeners": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Current listener count for this artist at this location." }, "prev_listeners": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Listener count from the previous snapshot." }, "artist_city_rank": { "type": [ "integer", "null" ], "description": "Artist's rank within this location." }, "max_listeners": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Maximum listener count for this artist across all snapshots." }, "population": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Population of the city or country." }, "city_affinity": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Artist's affinity score for the city." }, "is_estimate": { "type": [ "boolean", "null" ], "description": "True when the listener count is a Chartmetric estimate (post 2024-08-12 Spotify shift to estimates only)." } } } }, "description": "Map of country name → list of listener-count snapshots." } } } }, "additionalProperties": false }, "examples": { "default": { "value": { "obj": { "cities": { "Brisbane": [ { "timestp": "2024-10-15T07:00:00.000Z", "code2": "AU", "spotify_artist_id": "06HL4z0CvFAxyc27GXpf02", "lat": -27.455, "lng": 153.0351, "region": "CITY", "city_id": 591, "spotify_artist_insights_location": null, "current_max_count": 616040, "market_max_cm_artist_id": 212715, "market_max_artist_name": "Morgan Wallen", "listeners": 625990, "prev_listeners": 621474, "artist_city_rank": null, "max_listeners": 92958654, "population": 2360241, "city_affinity": null, "is_estimate": true } ] }, "countries": { "Australia": [ { "timestp": "2024-10-15T07:00:00.000Z", "code2": "AU", "spotify_artist_id": "06HL4z0CvFAxyc27GXpf02", "lat": -25.274398, "lng": 133.775136, "region": "COUNTRY", "city_id": 591, "spotify_artist_insights_location": null, "current_max_count": 616040, "market_max_cm_artist_id": null, "market_max_artist_name": null, "listeners": 5497904, "prev_listeners": 5508062, "artist_city_rank": null, "max_listeners": 92958654, "population": 26033500, "city_affinity": null, "is_estimate": true } ] } } } } } } } } } } }, "/api/artist/{id}/{platform}/{status}/playlists": { "get": { "summary": "💎 Premium — Playlists Featuring an Artist's Tracks", "tags": [ "Artist" ], "operationId": "listArtistPlaylists", "description": "Current or past playlists on `platform` (`spotify`, `applemusic`, `deezer`, `amazon`, `youtube`, `soundcloud`) that feature this artist's tracks. `status` is `current` or `past`.\n\n**Allowed `sortColumn` per (`platform`, `status`):**\n\n| platform | status | Valid `sortColumn` values |\n|---|---|---|\n| amazon | current | `added_at` (default), `countries`, `name`, `peak_position`, `track` |\n| applemusic | current | `added_at` (default), `name`, `peak_position`, `position`, `track` |\n| applemusic | past | `added_at`, `name`, `peak_position`, `position`, `removed_at` (default), `track` |\n| deezer | current | `added_at` (default), `fdiff_month`, `followers`, `name`, `peak_position`, `track` |\n| deezer | past | `added_at`, `fdiff_month`, `followers`, `name`, `peak_position`, `removed_at` (default), `track` |\n| spotify | current | `added_at`, `code2`, `fdiff_month`, `followers` (default), `name`, `peak_position`, `position`, `track` |\n| spotify | past | `added_at`, `code2`, `fdiff_month`, `followers` (default), `name`, `peak_position`, `position`, `removed_at`, `track` |\n| youtube | current | `added_at` (default), `name`, `peak_position`, `track`, `vdiff_month`, `views` |\n| youtube | past | `added_at`, `name`, `peak_position`, `removed_at` (default), `track`, `vdiff_month`, `views` |\n| soundcloud | current | `added_at`, `name`, `peak_position`, `position`, `track`, `likes`, `reposts` |\n| soundcloud | past | `added_at`, `name`, `peak_position`, `position`, `removed_at`, `track`, `likes`, `reposts` |\n\n**Boolean flag parameters supported per platform:**\n\n| Flag | spotify | applemusic | deezer | amazon |\n|---|:---:|:---:|:---:|:---:|\n| `editorial` | ✅ | ✅ | ✅ | |\n| `editorialBrand` | | ✅ | | |\n| `personalized` | ✅ | | | |\n| `deezerPartner` | | | ✅ | |\n| `chart` | ✅ | ✅ | ✅ | |\n| `thisIs` | ✅ | | | |\n| `hundredPercent` | | | ✅ | |\n| `newMusicFriday` | ✅ | | | |\n| `radio` | ✅ | ✅ | | |\n| `fullyPersonalized` | ✅ | | | |\n| `brand` | ✅ | | ✅ | |\n| `majorCurator` | ✅ | | ✅ | |\n| `musicBrand` | | ✅ | | |\n| `nonMusicBrand` | | ✅ | | |\n| `popularIndie` | ✅ | | ✅ | |\n| `indie` | ✅ | ✅ | ✅ | |\n| `audiobook` | ✅ | | | |\n| `personalityArtist` | | ✅ | | |\n\nAmazon does not accept any flags. Flags are not mutually exclusive — pass others as `false` to scope to one. When no flags are specified the API may return an empty array; specify flags explicitly to get data. PG aggregates (`followers`, `fdiff_*`, `num_track`) may surface as strings due to uncast COUNT/SUM.", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer", "minimum": 2, "maximum": 2147483647, "not": { "enum": [ 1 ] }, "description": "Chartmetric artist ID. Note: id=1 ('Various Artists') is rejected." }, "required": true, "description": "Chartmetric artist ID. Note: id=1 ('Various Artists') is rejected.", "examples": { "default": { "value": 2 } } }, { "name": "platform", "in": "path", "schema": { "type": "string", "enum": [ "spotify", "applemusic", "deezer", "amazon", "youtube", "soundcloud" ], "description": "Streaming platform. One of `spotify`, `applemusic`, `deezer`, `amazon`, `youtube`, `soundcloud`. Supported boolean filters and `sortColumn` values vary by platform." }, "required": true, "description": "Streaming platform. One of `spotify`, `applemusic`, `deezer`, `amazon`, `youtube`, `soundcloud`. Supported boolean filters and `sortColumn` values vary by platform.", "examples": { "default": { "value": "spotify" } } }, { "name": "status", "in": "path", "schema": { "type": "string", "enum": [ "current", "past" ], "description": "Playlist status. `current` returns playlists currently containing the artist's tracks; `past` returns playlists that previously did." }, "required": true, "description": "Playlist status. `current` returns playlists currently containing the artist's tracks; `past` returns playlists that previously did.", "examples": { "default": { "value": "current" } } }, { "name": "since", "in": "query", "schema": { "type": "string", "format": "date", "description": "Start of the added/removed date window in ISO format (e.g. '2025-11-01'). Defaults to 180 days ago.", "default": "2026-05-09" }, "required": false, "description": "Start of the added/removed date window in ISO format (e.g. '2025-11-01'). Defaults to 180 days ago." }, { "name": "until", "in": "query", "schema": { "type": "string", "format": "date", "description": "End of the added/removed date window in ISO format (e.g. '2025-11-01'). Defaults to today.", "default": "2026-11-05" }, "required": false, "description": "End of the added/removed date window in ISO format (e.g. '2025-11-01'). Defaults to today." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, "required": false, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum number of playlist entries to return. Defaults to 10, max 100.", "default": 10 }, "required": false, "description": "Maximum number of playlist entries to return. Defaults to 10, max 100." }, { "name": "indie", "in": "query", "schema": { "type": "boolean", "description": "Filter to only playlists tagged as indie (independently curated)." }, "required": false, "description": "Filter to only playlists tagged as indie (independently curated)." }, { "name": "majorCurator", "in": "query", "schema": { "type": "boolean", "description": "Filter to only playlists owned by a major-label curator (Sony, Universal, Warner, etc.)." }, "required": false, "description": "Filter to only playlists owned by a major-label curator (Sony, Universal, Warner, etc.)." }, { "name": "editorial", "in": "query", "schema": { "type": "boolean", "description": "Filter to only editorial playlists curated by the platform (e.g. Spotify-owned). Defaults to true; pass `false` to include user-curated playlists.", "default": true }, "required": false, "description": "Filter to only editorial playlists curated by the platform (e.g. Spotify-owned). Defaults to true; pass `false` to include user-curated playlists." }, { "name": "newMusicFriday", "in": "query", "schema": { "type": "boolean", "description": "Filter to only New Music Friday-style new-release playlists." }, "required": false, "description": "Filter to only New Music Friday-style new-release playlists." }, { "name": "editorialBrand", "in": "query", "schema": { "type": "boolean", "description": "Filter to only editorial playlists operated by a brand (e.g. retailer or media outlet)." }, "required": false, "description": "Filter to only editorial playlists operated by a brand (e.g. retailer or media outlet)." }, { "name": "personalized", "in": "query", "schema": { "type": "boolean", "description": "Filter to only personalized playlists (e.g. Discover Weekly, Release Radar). May vary per listener." }, "required": false, "description": "Filter to only personalized playlists (e.g. Discover Weekly, Release Radar). May vary per listener." }, { "name": "deezerPartner", "in": "query", "schema": { "type": "boolean", "description": "Filter to only Deezer partner-curated playlists." }, "required": false, "description": "Filter to only Deezer partner-curated playlists." }, { "name": "chart", "in": "query", "schema": { "type": "boolean", "description": "Filter to only chart playlists (e.g. Top 50, Viral 50). Reflects platform-published rankings." }, "required": false, "description": "Filter to only chart playlists (e.g. Top 50, Viral 50). Reflects platform-published rankings." }, { "name": "thisIs", "in": "query", "schema": { "type": "boolean", "description": "Filter to only artist-spotlight playlists in the 'This Is X' format." }, "required": false, "description": "Filter to only artist-spotlight playlists in the 'This Is X' format." }, { "name": "hundredPercent", "in": "query", "schema": { "type": "boolean", "description": "Filter to only playlists composed entirely of one artist's catalog." }, "required": false, "description": "Filter to only playlists composed entirely of one artist's catalog." }, { "name": "radio", "in": "query", "schema": { "type": "boolean", "description": "Filter to only algorithmic radio-style playlists generated from a seed track or artist." }, "required": false, "description": "Filter to only algorithmic radio-style playlists generated from a seed track or artist." }, { "name": "fullyPersonalized", "in": "query", "schema": { "type": "boolean", "description": "Filter to only fully personalized playlists where the entire tracklist is unique per listener." }, "required": false, "description": "Filter to only fully personalized playlists where the entire tracklist is unique per listener." }, { "name": "brand", "in": "query", "schema": { "type": "boolean", "description": "Filter to only brand-operated playlists (any flavor — music, non-music, retailer, media)." }, "required": false, "description": "Filter to only brand-operated playlists (any flavor — music, non-music, retailer, media)." }, { "name": "musicBrand", "in": "query", "schema": { "type": "boolean", "description": "Filter to only music-industry brand playlists (labels, music publications)." }, "required": false, "description": "Filter to only music-industry brand playlists (labels, music publications)." }, { "name": "nonMusicBrand", "in": "query", "schema": { "type": "boolean", "description": "Filter to only non-music-industry brand playlists (retailers, media outlets, lifestyle)." }, "required": false, "description": "Filter to only non-music-industry brand playlists (retailers, media outlets, lifestyle)." }, { "name": "popularIndie", "in": "query", "schema": { "type": "boolean", "description": "Filter to only popular indie playlists with significant follower count." }, "required": false, "description": "Filter to only popular indie playlists with significant follower count." }, { "name": "audiobook", "in": "query", "schema": { "type": "boolean", "description": "Filter to only audiobook playlists." }, "required": false, "description": "Filter to only audiobook playlists." }, { "name": "personalityArtist", "in": "query", "schema": { "type": "boolean", "description": "Filter to only playlists curated by personality artists (artists with cultural influence beyond their music)." }, "required": false, "description": "Filter to only playlists curated by personality artists (artists with cultural influence beyond their music)." }, { "name": "minFollowers", "in": "query", "schema": { "type": "integer", "description": "Minimum follower count for returned playlists. Defaults to 0 (no minimum)." }, "required": false, "description": "Minimum follower count for returned playlists. Defaults to 0 (no minimum)." }, { "name": "showPositionStats", "in": "query", "schema": { "type": "boolean", "description": "If true, include track position statistics on each playlist entry. Defaults to false.", "default": false }, "required": false, "description": "If true, include track position statistics on each playlist entry. Defaults to false." }, { "name": "sortColumn", "in": "query", "schema": { "type": "string", "description": "Column to sort playlists by. Allowed values depend on `(platform, status)` — see the platform-specific table in the apidoc." }, "required": false, "description": "Column to sort playlists by. Allowed values depend on `(platform, status)` — see the platform-specific table in the apidoc." }, { "name": "sortOrderDesc", "in": "query", "schema": { "type": "boolean", "description": "If true, sort descending by `sortColumn`. Only valid when `sortColumn` is also defined." }, "required": false, "description": "If true, sort descending by `sortColumn`. Only valid when `sortColumn` is also defined." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "array", "items": { "type": "object", "properties": { "playlist": { "type": "object", "properties": { "playlist_id": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "string" } ], "nullable": true, "description": "Platform-native playlist ID (e.g. Spotify URI suffix)." }, "track_id": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Internal track-link ID. Deprecated." }, "peak_position": { "type": [ "integer", "null" ], "description": "Track's best position on the playlist." }, "position": { "type": [ "integer", "null" ], "description": "Track's current position on the playlist." }, "cm_track": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Chartmetric track ID." }, "fdiff_month": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Monthly change in playlist follower count." }, "fdiff_week": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Weekly change in playlist follower count." }, "added_at": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Date the track was added to the playlist (ISO 8601)." }, "removed_at": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Date the track was removed from the playlist (ISO 8601), if applicable." }, "period": { "type": [ "integer", "null" ], "description": "Number of days the track has been on the playlist." }, "followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Most recent playlist follower count." }, "track": { "type": [ "string", "null" ], "description": "Track name (denormalized from the track row)." }, "id": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Chartmetric playlist ID." }, "name": { "type": [ "string", "null" ], "description": "Playlist title." }, "description": { "type": [ "string", "null" ], "description": "Playlist description." }, "image_url": { "type": [ "string", "null" ], "description": "Playlist cover image URL." }, "playlist_image_url": { "type": [ "string", "null" ], "description": "Playlist cover image URL (alternate field)." }, "sys_last_updated": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Date Chartmetric last updated this playlist record (ISO 8601)." }, "last_updated": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Date the platform last updated the playlist (ISO 8601)." }, "personalized": { "type": [ "boolean", "null" ], "description": "True for personalized playlists." }, "code2": { "type": [ "string", "null" ], "description": "Playlist country (ISO 3166-1 alpha-2)." }, "curator_name": { "type": [ "string", "null" ], "description": "Curator's display name." }, "owner_name": { "type": [ "string", "null" ], "description": "Playlist owner's display name." }, "owner_id": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 2147483647 }, { "type": "string" } ], "nullable": true, "description": "Chartmetric curator ID of the playlist owner." }, "user_id": { "type": [ "string", "null" ], "description": "Platform-native user ID of the playlist owner." }, "editorial": { "type": [ "boolean", "null" ], "description": "True for playlists curated by the platform editorial team (Spotify, Apple Music, Deezer)." }, "tags": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Chartmetric tag ID." }, "name": { "type": [ "string", "null" ], "description": "Tag name." } } }, "description": "List of playlist tags." }, "num_track": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Total number of tracks on the playlist." }, "catalog": { "type": [ "string", "null" ], "description": "Playlist catalog category (e.g. `mixed`, `frontline`)." }, "active_ratio": { "type": [ "number", "null" ], "format": "float", "description": "Ratio of active to total tracks on the playlist." } }, "description": "Playlist details (cover, curator, follower counts, tags, ...)." }, "track": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Internal track-link ID. Deprecated." }, "name": { "type": [ "string", "null" ], "description": "Track name." }, "isrc": { "type": [ "string", "null" ], "description": "International Standard Recording Code." }, "spotify_track_id": { "type": [ "string", "null" ], "description": "Primary Spotify track ID." }, "spotify_album_id": { "type": [ "string", "null" ], "description": "Primary Spotify album ID." }, "image_url": { "type": [ "string", "null" ], "description": "Track cover image URL." }, "spotify_popularity": { "type": [ "integer", "null" ], "description": "Spotify popularity score (0–100)." }, "cm_track": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Chartmetric track ID." }, "spotify_artist_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Spotify artist names credited on the track." }, "track_genre": { "anyOf": [ { "type": "string" }, { "type": "array", "items": {} } ], "nullable": true, "description": "Track genres (comma-joined string or array)." }, "cm_artist": { "type": [ "array", "null" ], "items": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "description": "List of Chartmetric artist IDs credited on the track." }, "artist_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Names of credited artists, parallel to `cm_artist`." }, "code2s": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Country codes of credited artists, parallel to `cm_artist`." }, "artist_images": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Image URLs of credited artists." }, "artist_covers": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Cover image URLs of credited artists." }, "spotify_artist_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Spotify artist IDs of credited artists." }, "spotify_track_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Spotify track IDs for the track." }, "spotify_album_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Spotify album IDs containing the track." }, "spotify_duration_ms": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "array", "items": { "type": "number", "format": "float" } } ], "nullable": true, "description": "Spotify track duration in milliseconds. May arrive as an array for multi-version tracks." }, "album_ids": { "type": [ "array", "null" ], "items": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "description": "Chartmetric album IDs containing the track." }, "album_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Album names parallel to `album_ids`." }, "album_upc": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Album UPCs parallel to `album_ids`." }, "album_label": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Album record labels parallel to `album_ids`." }, "release_dates": { "type": [ "array", "null" ], "items": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ] }, "description": "Release dates parallel to `album_ids`." }, "composer_name": { "type": [ "string", "null" ], "description": "Composer name credited for the track." }, "score": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric track score." }, "album": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Chartmetric album ID." }, "label": { "type": [ "string", "null" ], "description": "Record label." }, "name": { "type": [ "string", "null" ], "description": "Album name." }, "release_date": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Album release date (ISO 8601)." }, "upc": { "type": [ "string", "null" ], "description": "Universal Product Code." } } }, "description": "List of albums containing the track." } }, "description": "Track details (the artist's track that appears on this playlist)." } } } } }, "required": [ "obj" ], "additionalProperties": false }, "examples": { "default": { "value": { "obj": [ { "playlist": { "playlist_id": "24rm8nmbUoNGOPmHuHo82X", "track_id": 130396669, "peak_position": 335, "position": 335, "cm_track": 111516408, "fdiff_month": 0, "added_at": "2023-10-04", "period": 19, "followers": 1, "track": "Bad Girls", "name": "Линочке", "playlist_image_url": "https://image-cdn-ak.spotifycdn.com/image/ab67706c0000bebba87504063ea6446e82dff60f", "code2": null, "curator_name": "Влад", "id": 15853738, "description": "Playlist description…", "image_url": "https://image-cdn-ak.spotifycdn.com/image/ab67706c0000bebba87504063ea6446e82dff60f", "sys_last_updated": "2023-10-19T00:00:00.000Z", "last_updated": "2023-10-19T20:26:31.000Z", "personalized": false, "owner_name": "Влад", "owner_id": 24259895, "user_id": "5xb0g5od6z0chmrv5z9txji2d", "editorial": false, "tags": [ { "id": 462884, "name": "Rock" }, { "id": 462888, "name": "Alternative" } ], "num_track": 344, "fdiff_week": 0, "catalog": "mixed", "active_ratio": 0.06686 }, "track": { "id": 130396669, "name": "Bad Girls", "isrc": "QZWDD2334631", "spotify_track_id": "5U6zdFSc5WJWr1E3O1f3T1", "spotify_album_id": "1W0rzr5HFU9b5hp8TMjk3T", "image_url": "https://i.scdn.co/image/ab67616d0000b273302fe5d2572cb5def4a5f9f2", "spotify_popularity": 0, "cm_track": 111516408, "spotify_artist_names": [ "Lvvrs" ], "track_genre": null, "cm_artist": [ 1022311 ], "artist_names": [ "Lvvrs" ], "code2s": [ "US" ], "artist_images": [ "https://i.scdn.co/image/ab67616100005174e9691106aa3d936390cc799e" ], "artist_covers": [ null ], "spotify_artist_ids": [ "6VJa7asxiDZyqRa94XNRLA" ], "spotify_track_ids": [ "5U6zdFSc5WJWr1E3O1f3T1" ], "spotify_album_ids": [ "1W0rzr5HFU9b5hp8TMjk3T" ], "spotify_duration_ms": 175798, "album_ids": [ 30925539 ], "album_names": [ "Bad Girls" ], "album_upc": [ "197773755869" ], "album_label": [ "LVVRS" ], "release_dates": [ "2023-09-15" ], "composer_name": null } } ] } } } } } } } } }, "/api/artist/{id}/albums": { "get": { "summary": "List Albums Featuring an Artist", "tags": [ "Artist" ], "operationId": "listArtistAlbums", "description": "Albums featuring this artist. Supports sorting by any column the underlying query understands, pagination via `limit`/`offset`, and `isPrimary=true` to restrict to albums where the artist is the primary artist.", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer", "minimum": 2, "maximum": 2147483647, "not": { "enum": [ 1 ] }, "description": "Chartmetric artist ID. Note: id=1 ('Various Artists') is rejected." }, "required": true, "description": "Chartmetric artist ID. Note: id=1 ('Various Artists') is rejected.", "examples": { "default": { "value": 2 } } }, { "name": "sortColumn", "in": "query", "schema": { "type": "string", "enum": [ "release_date", "spotify_popularity" ], "description": "Column to sort albums by. One of `release_date`, `spotify_popularity`. Defaults to `release_date`.", "default": "release_date" }, "required": false, "description": "Column to sort albums by. One of `release_date`, `spotify_popularity`. Defaults to `release_date`." }, { "name": "sortOrderDesc", "in": "query", "schema": { "type": "boolean", "description": "If true (default), sort descending by `sortColumn`.", "default": true }, "required": false, "description": "If true (default), sort descending by `sortColumn`." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "description": "Maximum number of albums to return. Defaults to 100.", "default": 100 }, "required": false, "description": "Maximum number of albums to return. Defaults to 100." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, "required": false, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, { "name": "isPrimary", "in": "query", "schema": { "type": "boolean", "description": "If true, return only albums where the artist is one of the main credited artists. Defaults to false.", "default": false }, "required": false, "description": "If true, return only albums where the artist is one of the main credited artists. Defaults to false." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Chartmetric album ID." }, "upc": { "type": [ "string", "null" ], "description": "Universal Product Code identifying the release." }, "name": { "type": [ "string", "null" ], "description": "Album name." }, "local_name": { "type": [ "string", "null" ], "description": "Localized album name, when available." }, "local_name_locale": { "type": [ "string", "null" ], "description": "Locale for local_name, when available." }, "image_url": { "type": [ "string", "null" ], "description": "Album cover image URL." }, "release_date": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Album release date (ISO 8601)." }, "label": { "type": [ "string", "null" ], "description": "Record label that released the album." }, "spotify_popularity": { "type": [ "integer", "null" ], "description": "Spotify popularity score for the album (0–100)." }, "cm_label": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Chartmetric label ID." }, "description": { "type": [ "string", "null" ], "description": "Album description." }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Date the album record was created in Chartmetric (ISO 8601)." }, "modified_at": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Date the album record was last modified in Chartmetric (ISO 8601)." }, "cm_album": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Chartmetric album ID." }, "num_track": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Number of tracks on the album. May arrive as string." }, "spotify_album_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Spotify album IDs linked to this Chartmetric album." }, "itunes_album_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "iTunes album IDs linked to this Chartmetric album." }, "deezer_album_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Deezer album IDs linked to this Chartmetric album." }, "artists": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "cm_artist": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Chartmetric artist ID." }, "name": { "type": [ "string", "null" ], "description": "Artist name." }, "image_url": { "type": [ "string", "null" ], "description": "Artist image URL." } } }, "description": "List of artists credited on the album." } } } } }, "required": [ "obj" ], "additionalProperties": false }, "examples": { "default": { "value": { "obj": [ { "id": 370590, "upc": "886444975025", "name": "BEYONCÉ [Platinum Edition]", "local_name": null, "local_name_locale": null, "image_url": "https://i.scdn.co/image/fd3cac76a8f1f3cab516f06873eeec16977efdf0", "release_date": "2014-11-24T00:00:00.000Z", "label": "Parkwood Entertainment/Columbia", "spotify_popularity": 77, "cm_label": 41089, "description": null, "created_at": null, "modified_at": "2020-06-02T00:00:28.227Z", "cm_album": 370590, "num_track": "20", "spotify_album_ids": [ "2UJwKSBUz6rtW4QLK74kQu" ], "itunes_album_ids": [ "1308530355", "939780552" ], "deezer_album_ids": [ "9163719" ], "artists": [ { "cm_artist": 2838, "name": "Beyoncé", "image_url": "https://i.scdn.co/image/ad8b0e5a18a5a443a2678768bd73f59833941abc" } ] } ] } } } } } } } } }, "/api/artist/{id}/tracks": { "get": { "summary": "List Tracks by Artist", "tags": [ "Artist" ], "operationId": "listArtistTracks", "description": "Tracks by this artist, including featured collaborations. Supports pagination via `offset`/`limit`, filtering by `artist_type` and by track `version_*` flags (`version_only`, `version_and`, `version_or`, `version_not`). Top-level `total` is the ES-backed artist track count. Mash-up tracks are currently treated as original tracks.", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer", "minimum": 2, "maximum": 2147483647, "not": { "enum": [ 1 ] }, "description": "Chartmetric artist ID. Note: id=1 ('Various Artists') is rejected." }, "required": true, "description": "Chartmetric artist ID. Note: id=1 ('Various Artists') is rejected.", "examples": { "default": { "value": 2 } } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, "required": false, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "description": "Maximum number of tracks to return. Defaults to 10, max 200.", "default": 10 }, "required": false, "description": "Maximum number of tracks to return. Defaults to 10, max 200." }, { "name": "artist_type", "in": "query", "schema": { "type": "string", "enum": [ "main", "featured" ], "description": "Filter by artist role on the track. Omit to return both." }, "required": false, "description": "Filter by artist role on the track. Omit to return both." }, { "name": "version_only[]", "in": "query", "schema": { "type": "array", "items": { "type": "string", "enum": [ "original", "re_release", "edit", "remix", "acoustic", "alt_ver", "physical_ver", "cover", "live", "feat_or_collab", "dub", "remaster", "bonus", "arrangement", "commentary", "lofi", "component", "karaoke", "compilation_rerelease", "explicit", "clean", "other" ] }, "description": "Return only tracks matching ALL of these version types (AND logic). CANNOT be combined with version_and, version_or, or version_not." }, "required": false, "description": "Return only tracks matching ALL of these version types (AND logic). CANNOT be combined with version_and, version_or, or version_not." }, { "name": "version_and[]", "in": "query", "schema": { "type": "array", "items": { "type": "string", "enum": [ "original", "re_release", "edit", "remix", "acoustic", "alt_ver", "physical_ver", "cover", "live", "feat_or_collab", "dub", "remaster", "bonus", "arrangement", "commentary", "lofi", "component", "karaoke", "compilation_rerelease", "explicit", "clean", "other" ] }, "description": "Return tracks that have ALL of these version types (AND logic). CANNOT be combined with version_only or version_or. Can be combined with version_not." }, "required": false, "description": "Return tracks that have ALL of these version types (AND logic). CANNOT be combined with version_only or version_or. Can be combined with version_not." }, { "name": "version_or[]", "in": "query", "schema": { "type": "array", "items": { "type": "string", "enum": [ "original", "re_release", "edit", "remix", "acoustic", "alt_ver", "physical_ver", "cover", "live", "feat_or_collab", "dub", "remaster", "bonus", "arrangement", "commentary", "lofi", "component", "karaoke", "compilation_rerelease", "explicit", "clean", "other" ] }, "description": "Return tracks that have ANY of these version types (OR logic). CANNOT be combined with version_only or version_and. Can be combined with version_not." }, "required": false, "description": "Return tracks that have ANY of these version types (OR logic). CANNOT be combined with version_only or version_and. Can be combined with version_not." }, { "name": "version_not[]", "in": "query", "schema": { "type": "array", "items": { "type": "string", "enum": [ "original", "re_release", "edit", "remix", "acoustic", "alt_ver", "physical_ver", "cover", "live", "feat_or_collab", "dub", "remaster", "bonus", "arrangement", "commentary", "lofi", "component", "karaoke", "compilation_rerelease", "explicit", "clean", "other" ] }, "description": "Exclude tracks matching any of these version types. CANNOT be combined with version_only. Can be combined with version_and or version_or." }, "required": false, "description": "Exclude tracks matching any of these version types. CANNOT be combined with version_only. Can be combined with version_and or version_or." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Chartmetric track ID. Deprecated alias for `cm_track`." }, "cm_track": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Chartmetric track ID." }, "isrc": { "type": [ "string", "null" ], "description": "International Standard Recording Code." }, "name": { "type": [ "string", "null" ], "description": "Track name." }, "local_name": { "type": [ "string", "null" ], "description": "Localized track name, when available." }, "local_name_locale": { "type": [ "string", "null" ], "description": "Locale for local_name, when available." }, "image_url": { "type": [ "string", "null" ], "description": "Track cover image URL." }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Date this track record was created (ISO 8601)." }, "modified_at": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Date this track record was last modified (ISO 8601)." }, "description": { "type": [ "string", "null" ], "description": "Track description. Deprecated and currently always null." }, "tags": { "type": [ "string", "null" ], "description": "Comma-separated list of genres for the track." }, "artist_type": { "type": [ "string", "null" ], "description": "Artist's role on the track (`main` or `featured`)." }, "cm_artist": { "type": [ "array", "null" ], "items": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "description": "List of Chartmetric artist IDs credited on the track." }, "artist_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Names of credited artists, parallel to `cm_artist`." }, "code2s": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Country codes (ISO 3166-1 alpha-2) of credited artists, parallel to `cm_artist`." }, "artist_images": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Image URLs of credited artists, parallel to `cm_artist`." }, "artist_covers": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Cover image URLs of credited artists, parallel to `cm_artist`." }, "spotify_track_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Spotify track IDs linked to this Chartmetric track." }, "spotify_album_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Spotify album IDs containing this track." }, "spotify_duration_ms": { "type": [ "integer", "null" ], "minimum": 0, "description": "Spotify track duration in milliseconds." }, "itunes_track_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "iTunes track IDs linked to this Chartmetric track." }, "itunes_album_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "iTunes album IDs containing this track." }, "storefronts": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "iTunes storefront codes where this track is available." }, "deezer_track_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Deezer track IDs linked to this Chartmetric track." }, "deezer_album_ids": { "type": [ "array", "null" ], "items": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ] }, "description": "Deezer album IDs containing this track." }, "deezer_duration": { "type": [ "integer", "null" ], "minimum": 0, "description": "Deezer track duration in seconds." }, "amazon_track_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Amazon track IDs linked to this Chartmetric track." }, "amazon_album_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Amazon album IDs containing this track." }, "album_ids": { "type": [ "array", "null" ], "items": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "description": "Chartmetric album IDs containing this track." }, "album_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Album names parallel to `album_ids`." }, "album_upc": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Album UPCs parallel to `album_ids`." }, "album_label": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Album record labels parallel to `album_ids`." }, "release_dates": { "type": [ "array", "null" ], "items": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ] }, "description": "Release dates parallel to `album_ids`." }, "genre_smart_ordered": { "type": [ "array", "null" ], "items": { "type": "object", "properties": {} }, "description": "List of single-key objects mapping order index to genre ID, ordered by relevance." }, "cm_statistics": { "type": [ "object", "null" ], "properties": { "cm_track": { "type": [ "integer", "null" ], "description": "Chartmetric track ID (same as outer `id`)." }, "sp_popularity": { "type": [ "integer", "null" ], "description": "Spotify popularity score (0–100)." }, "num_sp_playlists": { "type": [ "integer", "null" ], "description": "Number of Spotify playlists featuring this track." }, "num_sp_editorial_playlists": { "type": [ "integer", "null" ], "description": "Number of Spotify editorial playlists featuring this track." }, "num_am_playlists": { "type": [ "integer", "null" ], "description": "Number of Apple Music playlists featuring this track." }, "num_am_editorial_playlists": { "type": [ "integer", "null" ], "description": "Number of Apple Music editorial playlists featuring this track." }, "num_de_playlists": { "type": [ "integer", "null" ], "description": "Number of Deezer playlists featuring this track." }, "num_de_editorial_playlists": { "type": [ "integer", "null" ], "description": "Number of Deezer editorial playlists featuring this track." }, "num_az_playlists": { "type": [ "integer", "null" ], "description": "Number of Amazon playlists featuring this track." }, "num_az_editorial_playlists": { "type": [ "integer", "null" ], "description": "Number of Amazon editorial playlists featuring this track." }, "num_yt_playlists": { "type": [ "integer", "null" ], "description": "Number of YouTube playlists featuring this track." }, "num_yt_editorial_playlists": { "type": [ "integer", "null" ], "description": "Number of YouTube editorial playlists featuring this track." }, "num_tt_videos": { "type": [ "integer", "null" ], "description": "TikTok video count using this track." }, "sp_playlist_total_reach": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Sum of followers across all Spotify playlists featuring the track. Surfaces as string from PG uncast aggregate." }, "sp_editorial_playlist_total_reach": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Sum of followers across Spotify editorial playlists featuring the track." }, "de_playlist_total_reach": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Sum of fans across all Deezer playlists featuring the track." }, "de_editorial_playlist_total_reach": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Sum of fans across Deezer editorial playlists featuring the track." }, "yt_playlist_total_reach": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Sum of views across all YouTube playlists featuring the track." }, "yt_editorial_playlist_total_reach": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Sum of views across YouTube editorial playlists featuring the track." }, "sp_streams": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Total Spotify stream count. May exceed int32 and arrive as string." }, "youtube_views": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Total YouTube view count. May exceed int32 and arrive as string." }, "soundcloud_playback_count": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Total SoundCloud playback count." }, "genius_page_views": { "type": [ "integer", "null" ], "description": "Genius lyrics page view count." }, "shazam_counts": { "type": [ "integer", "null" ], "description": "Total Shazam tag count." }, "tiktok_counts": { "type": [ "integer", "null" ], "description": "TikTok counter (legacy — alias of `num_tt_videos`)." }, "tiktok_trending_user": { "type": [ "string", "null" ], "description": "TikTok trending user ID for the track." }, "tiktok_trending_user_likes": { "type": [ "string", "null" ], "description": "TikTok trending user like count." }, "tiktok_trending_user_cm_artist": { "type": [ "integer", "null" ], "description": "Chartmetric artist ID of the TikTok trending user." }, "pandora_lifetime_streams": { "type": [ "integer", "null" ], "description": "Pandora lifetime stream count." }, "pandora_lifetime_stations_added": { "type": [ "integer", "null" ], "description": "Pandora lifetime stations-added count." }, "boomplay_comments": { "type": [ "string", "null" ], "description": "Boomplay comment count." }, "boomplay_favorites": { "type": [ "string", "null" ], "description": "Boomplay favorite count." }, "boomplay_shares": { "type": [ "string", "null" ], "description": "Boomplay share count." }, "line_music_likes": { "type": [ "string", "null" ], "description": "Line Music like count." }, "line_music_listen_count": { "type": [ "string", "null" ], "description": "Line Music listen count." }, "melon_likes": { "type": [ "string", "null" ], "description": "Melon like count." } }, "description": "Aggregated platform counters. Large counters (streams, views, playlist reach) surface as strings from uncast PG aggregates; small bounded counts stay numeric. Additional undocumented platform counters may appear as new sources are integrated." }, "cm_audio_features": { "type": [ "object", "null" ], "properties": { "acousticness": { "type": [ "integer", "null" ], "description": "Acousticness (deprecated, hard-coded to 0)." }, "danceability": { "type": [ "integer", "null" ], "description": "Danceability (deprecated, hard-coded to 0)." }, "energy": { "type": [ "integer", "null" ], "description": "Energy (deprecated, hard-coded to 0)." }, "instrumentalness": { "type": [ "integer", "null" ], "description": "Instrumentalness (deprecated, hard-coded to 0)." }, "key": { "type": [ "integer", "null" ], "description": "Musical key (deprecated, hard-coded to 0)." }, "liveness": { "type": [ "integer", "null" ], "description": "Liveness (deprecated, hard-coded to 0)." }, "loudness": { "type": [ "integer", "null" ], "description": "Loudness (deprecated, hard-coded to 0)." }, "mode": { "type": [ "integer", "null" ], "description": "Musical mode (deprecated, hard-coded to 0)." }, "speechiness": { "type": [ "integer", "null" ], "description": "Speechiness (deprecated, hard-coded to 0)." }, "tempo": { "type": [ "integer", "null" ], "description": "Tempo (deprecated, hard-coded to 0)." }, "valence": { "type": [ "integer", "null" ], "description": "Valence (deprecated, hard-coded to 0)." } }, "description": "Chartmetric audio features. Deprecated — every field is hard-coded to `0` and the object will be removed in a future release.", "deprecated": true }, "cm_track_cluster": { "type": [ "object", "null" ], "properties": { "cluster_id": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Chartmetric cluster ID; tracks in the same cluster are versions of one work." }, "track_types": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "List of version types present in the cluster (e.g. `original`, `remix`, `cover`)." } }, "description": "Cluster grouping for track versions. `null` when the track is standalone." }, "version_types": { "type": [ "object", "null" ], "properties": {}, "additionalProperties": { "type": "boolean" }, "description": "Map of version-type name → boolean indicating which version types apply to this track. When `cm_track_cluster` is null, this track is treated as the original version." } } } }, "total": { "type": [ "integer", "null" ], "minimum": 0, "description": "Total number of tracks for this artist in the Chartmetric catalog." } }, "required": [ "obj" ] }, "examples": { "default": { "value": { "obj": [ { "id": 12570005, "isrc": "GBBKS1200020", "artist_type": "featured", "cm_artist": [ 965, 3986 ], "artist_names": [ "Bobby Womack", "Lana Del Rey" ], "code2s": [ "US", "US" ], "artist_images": [ null, null ], "artist_covers": [ null, null ], "spotify_track_ids": [ "3Z1C7835mW8HCXECwVT5pB" ], "spotify_album_ids": [ "3Oy5qaBEIzs9KZVDMwvYI5" ], "spotify_duration_ms": 259906, "itunes_track_ids": [ "609128028" ], "itunes_album_ids": [ "609127619" ], "storefronts": [ "US" ], "deezer_track_ids": [ "32936061" ], "deezer_album_ids": [ 3174991 ], "deezer_duration": 258, "amazon_track_ids": null, "amazon_album_ids": null, "album_ids": [ 140496 ], "album_names": [ "The Bravest Man in the Universe" ], "album_upc": [ "614027871569" ], "album_label": [ "XL Recordings" ], "release_dates": [ "2012-06-08T00:00:00.000Z" ], "created_at": "2025-08-01T04:38:14Z", "image_url": "https://i.scdn.co/image/8feee61973cc047e433e6f150b2be32e354ba503", "name": "Dayglo Reflection", "cm_track": 12570005, "cm_track_cluster": { "cluster_id": 12570005, "track_types": [ "original", "clean" ] }, "cm_statistics": { "cm_track": 12570005, "num_sp_playlists": 2886, "num_sp_editorial_playlists": 2, "sp_playlist_total_reach": 548058, "sp_popularity": 40 }, "version_types": { "original": true, "re_release": false, "edit": false, "clean": false, "other": false } } ], "total": 120 } } } } } } } } }, "/api/artist/{id}/urls": { "get": { "summary": "Artist Social / Streaming Service URLs", "tags": [ "Artist" ], "operationId": "listArtistSocialUrls", "description": "Social media and streaming service URLs belonging to this artist. `url` is typically a string but can legally be an array of strings (per SNS record shape) or an empty value. Domains seen in production include `spotify`, `amazon`, `youtubeforartist`, `tvmaze`, `shazam`, `soundcloud`, `genius`, `website`, `lastfm`, `itunes`, `deezer`, `bandsintown`, `instagram`, `songkick`, `gtrends`, `discogs`, `wikipedia`, `twitter`, `youtube`, `facebook`. When the artist has no SNS record the response is `{ obj: {} }` (object instead of array). Note: the `musicbrainz` domain is deprecated and will be removed after August 1st, 2026 — existing values are still echoed in the response until then, but new MusicBrainz URLs are no longer accepted.", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer", "minimum": 2, "maximum": 2147483647, "not": { "enum": [ 1 ] }, "description": "Chartmetric artist ID. Note: id=1 ('Various Artists') is rejected." }, "required": true, "description": "Chartmetric artist ID. Note: id=1 ('Various Artists') is rejected.", "examples": { "default": { "value": 2 } } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": [ "string", "null" ], "description": "Source domain (e.g. `spotify`, `instagram`, `youtube`, `tvmaze`, `wikipedia`)." }, "url": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "nullable": true, "description": "Profile URL on the domain. Usually a string; may be an array of strings or empty." } } } }, { "type": "object", "properties": {} } ] } }, "required": [ "obj" ], "additionalProperties": false }, "examples": { "default": { "value": { "obj": [ { "domain": "spotify", "url": [ "https://open.spotify.com/artist/3TVXtAsR1Inumwj472S9r4" ] }, { "domain": "instagram", "url": [ "https://www.instagram.com/champagnepapi/?hl=en" ] }, { "domain": "twitter", "url": [ "https://twitter.com/Drake" ] }, { "domain": "youtube", "url": [ "https://www.youtube.com/channel/UCByOQJjav0CUDwxCk-jVNRQ" ] }, { "domain": "website", "url": [ "http://www.drakeofficial.com/" ] } ] } } } } } } } } }, "/api/artist/{id}/stat/{source}": { "get": { "summary": "Artist Fan Metrics by Source", "tags": [ "Artist" ], "operationId": "getArtistStatBySource", "description": "Artist's fan-metrics time series for a given `source`. Pass `field` to target a single metric, or omit it to receive the source's default fields. Each metric resolves to an array of time-series points with `value`, `timestp`, diff counters, and an `interpolated` flag (response may omit points on missing days; see the `interpolated: true|false` flag on each point).\n\n**Valid `field` values per `source`:**\n\n| source | Valid `field` values |\n|---|---|\n| `spotify` | `followers`, `popularity`, `listeners` |\n| `deezer` | `fans` |\n| `facebook` | `likes`, `talks` |\n| `twitter` | `followers`, `retweets` |\n| `youtube_channel` (artist's channel) | `subscribers`, `views`, `comments`, `videos` |\n| `youtube_artist` (channel + featured videos) | `daily_views`, `monthly_views` |\n| `instagram` | `followers` |\n| `wikipedia` | `views` |\n| `bandsintown` | `followers` |\n| `soundcloud` | `followers` |\n| `tiktok` | `followers`, `likes` |\n| `twitch` | `follower_count`, `monthly_viewer_hours`, `weekly_viewer_hours` |\n| `line` | `likes` |\n| `melon` | `fans` |\n| `bilibili` | `followers` |\n| `snap` | `story_views`, `spotlite_views`, `snap_followers` |\n\nIf `field` is omitted, the handler returns the source's default fields.\n\n**Geo filters per `(source, field)`:** these combinations are enforced — passing `city_id` or `code2` outside the table returns 400.\n\n| source | field | Comparable by city (`city_id`) | Comparable by country (`code2`) |\n|---|---|:---:|:---:|\n| `instagram` | `followers` | ✅ | ✅ |\n| `spotify` | `listeners` | ✅ | |\n| `tiktok` | `followers` | | ✅ |\n| `youtube_channel` | `subscribers` | | ✅ |\n| `youtube_artist` | `daily_views` | ✅ | ✅ |\n| `youtube_artist` | `monthly_views` | ✅ | ✅ |", "parameters": [ { "name": "id", "in": "path", "schema": { "anyOf": [ { "type": "string" }, { "type": "integer" } ], "description": "Artist identifier. Numeric Chartmetric artist ID by default; pass a domain-specific ID (e.g. Spotify artist hash, YouTube channel ID, TikTok handle) when `isDomainId=true`." }, "required": true, "description": "Artist identifier. Numeric Chartmetric artist ID by default; pass a domain-specific ID (e.g. Spotify artist hash, YouTube channel ID, TikTok handle) when `isDomainId=true`.", "examples": { "default": { "value": "2762" } } }, { "name": "source", "in": "path", "schema": { "type": "string", "enum": [ "spotify", "deezer", "facebook", "twitter", "instagram", "youtube_channel", "youtube_artist", "wikipedia", "bandsintown", "soundcloud", "tiktok", "twitch", "line", "melon", "bilibili", "snap" ], "description": "Data source. One of `spotify`, `deezer`, `facebook`, `twitter`, `instagram`, `youtube_channel`, `youtube_artist`, `wikipedia`, `bandsintown`, `soundcloud`, `tiktok`, `twitch`, `line`, `melon`, `bilibili`, `snap`. Each source supports a different default `field` set when `field` is omitted." }, "required": true, "description": "Data source. One of `spotify`, `deezer`, `facebook`, `twitter`, `instagram`, `youtube_channel`, `youtube_artist`, `wikipedia`, `bandsintown`, `soundcloud`, `tiktok`, `twitch`, `line`, `melon`, `bilibili`, `snap`. Each source supports a different default `field` set when `field` is omitted.", "examples": { "default": { "value": "spotify" } } }, { "name": "since", "in": "query", "schema": { "type": "string", "format": "date-time", "description": "Start of the date range in ISO format (e.g. '2025-11-01'). Defaults to 20 days ago. Ignored when `latest=true`.", "default": "2026-10-16" }, "required": false, "description": "Start of the date range in ISO format (e.g. '2025-11-01'). Defaults to 20 days ago. Ignored when `latest=true`." }, { "name": "until", "in": "query", "schema": { "type": "string", "format": "date-time", "description": "End of the date range in ISO format (e.g. '2025-11-01'). Defaults to today. Ignored when `latest=true`.", "default": "2026-11-05" }, "required": false, "description": "End of the date range in ISO format (e.g. '2025-11-01'). Defaults to today. Ignored when `latest=true`." }, { "name": "field", "in": "query", "schema": { "type": "string", "enum": [ "views", "subscribers", "likes", "followers", "talks", "favorites", "friends", "popularity", "listeners", "retweets", "comments", "videos", "followers_to_listeners_ratio", "daily_views", "monthly_views", "follower_count", "monthly_viewer_hours", "weekly_viewer_hours", "artist_likes", "fans", "story_views", "spotlite_views" ], "description": "Specific stat from `source` (e.g. `followers`, `popularity`, `listeners`, `talks`, `subscribers`). When omitted, returns the source-specific default field set." }, "required": false, "description": "Specific stat from `source` (e.g. `followers`, `popularity`, `listeners`, `talks`, `subscribers`). When omitted, returns the source-specific default field set." }, { "name": "latest", "in": "query", "schema": { "type": "boolean", "description": "If true, returns only the most recent data point and ignores `since`/`until`." }, "required": false, "description": "If true, returns only the most recent data point and ignores `since`/`until`." }, { "name": "interpolated", "in": "query", "schema": { "type": "boolean", "description": "If true, fill missing days with linear-interpolated values (average of bracketing observations). Not applicable to Spotify popularity or some interpolation-incompatible metrics." }, "required": false, "description": "If true, fill missing days with linear-interpolated values (average of bracketing observations). Not applicable to Spotify popularity or some interpolation-incompatible metrics." }, { "name": "isDomainId", "in": "query", "schema": { "type": "boolean", "description": "If true, treat `id` as a domain-specific ID rather than a Chartmetric artist ID. Defaults to false.", "default": false }, "required": false, "description": "If true, treat `id` as a domain-specific ID rather than a Chartmetric artist ID. Defaults to false." }, { "name": "city_id", "in": "query", "schema": { "anyOf": [ { "type": "integer", "minimum": 0 } ], "description": "Chartmetric city ID for city-scoped metrics. Mutually exclusive with `code2`. Only valid for `(source, field)` combos that support city comparison." }, "required": false, "description": "Chartmetric city ID for city-scoped metrics. Mutually exclusive with `code2`. Only valid for `(source, field)` combos that support city comparison." }, { "name": "code2", "in": "query", "schema": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB')." }, "required": false, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB')." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "object", "properties": { "link": { "type": [ "string", "null" ], "description": "Source-platform profile URL associated with the artist." }, "followers": { "type": "array", "items": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Metric value at this timestamp. May arrive as string for some uncast aggregates." }, "timestp": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Timestamp of the data point (ISO 8601)." }, "flags": { "type": [ "boolean", "null" ], "description": "Internal source-data flag for the point." }, "diff": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Daily change in `value` since the previous data point." }, "weekly_diff": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Change in `value` versus 7 days ago." }, "weekly_diff_percent": { "type": [ "number", "null" ], "format": "float", "description": "Percentage change in `value` versus 7 days ago." }, "monthly_diff": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Change in `value` versus 28 days ago." }, "monthly_diff_percent": { "type": [ "number", "null" ], "format": "float", "description": "Percentage change in `value` versus 28 days ago." }, "daily_diff": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Daily change. Emitted only when `interpolated=true`." }, "interpolated": { "type": [ "boolean", "null" ], "description": "True when this point was synthesized via linear interpolation rather than sourced directly. Not applicable to Spotify popularity." }, "extrapolated": { "type": [ "boolean", "null" ], "description": "True when this point was synthesized via extrapolation past the source-data window." } } }, "description": "Time series of follower counts on the source platform." }, "popularity": { "type": "array", "items": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Metric value at this timestamp. May arrive as string for some uncast aggregates." }, "timestp": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Timestamp of the data point (ISO 8601)." }, "flags": { "type": [ "boolean", "null" ], "description": "Internal source-data flag for the point." }, "diff": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Daily change in `value` since the previous data point." }, "weekly_diff": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Change in `value` versus 7 days ago." }, "weekly_diff_percent": { "type": [ "number", "null" ], "format": "float", "description": "Percentage change in `value` versus 7 days ago." }, "monthly_diff": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Change in `value` versus 28 days ago." }, "monthly_diff_percent": { "type": [ "number", "null" ], "format": "float", "description": "Percentage change in `value` versus 28 days ago." }, "daily_diff": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Daily change. Emitted only when `interpolated=true`." }, "interpolated": { "type": [ "boolean", "null" ], "description": "True when this point was synthesized via linear interpolation rather than sourced directly. Not applicable to Spotify popularity." }, "extrapolated": { "type": [ "boolean", "null" ], "description": "True when this point was synthesized via extrapolation past the source-data window." } } }, "description": "Time series of Spotify popularity scores (0–100)." }, "listeners": { "type": "array", "items": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Metric value at this timestamp. May arrive as string for some uncast aggregates." }, "timestp": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Timestamp of the data point (ISO 8601)." }, "flags": { "type": [ "boolean", "null" ], "description": "Internal source-data flag for the point." }, "diff": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Daily change in `value` since the previous data point." }, "weekly_diff": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Change in `value` versus 7 days ago." }, "weekly_diff_percent": { "type": [ "number", "null" ], "format": "float", "description": "Percentage change in `value` versus 7 days ago." }, "monthly_diff": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Change in `value` versus 28 days ago." }, "monthly_diff_percent": { "type": [ "number", "null" ], "format": "float", "description": "Percentage change in `value` versus 28 days ago." }, "daily_diff": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Daily change. Emitted only when `interpolated=true`." }, "interpolated": { "type": [ "boolean", "null" ], "description": "True when this point was synthesized via linear interpolation rather than sourced directly. Not applicable to Spotify popularity." }, "extrapolated": { "type": [ "boolean", "null" ], "description": "True when this point was synthesized via extrapolation past the source-data window." } } }, "description": "Time series of Spotify monthly listener counts." }, "followers_to_listeners_ratio": { "type": "array", "items": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Metric value at this timestamp. May arrive as string for some uncast aggregates." }, "timestp": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Timestamp of the data point (ISO 8601)." }, "flags": { "type": [ "boolean", "null" ], "description": "Internal source-data flag for the point." }, "diff": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Daily change in `value` since the previous data point." }, "weekly_diff": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Change in `value` versus 7 days ago." }, "weekly_diff_percent": { "type": [ "number", "null" ], "format": "float", "description": "Percentage change in `value` versus 7 days ago." }, "monthly_diff": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Change in `value` versus 28 days ago." }, "monthly_diff_percent": { "type": [ "number", "null" ], "format": "float", "description": "Percentage change in `value` versus 28 days ago." }, "daily_diff": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Daily change. Emitted only when `interpolated=true`." }, "interpolated": { "type": [ "boolean", "null" ], "description": "True when this point was synthesized via linear interpolation rather than sourced directly. Not applicable to Spotify popularity." }, "extrapolated": { "type": [ "boolean", "null" ], "description": "True when this point was synthesized via extrapolation past the source-data window." } } }, "description": "Time series of Spotify followers-to-listeners ratio." }, "fans": { "type": "array", "items": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Metric value at this timestamp. May arrive as string for some uncast aggregates." }, "timestp": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Timestamp of the data point (ISO 8601)." }, "flags": { "type": [ "boolean", "null" ], "description": "Internal source-data flag for the point." }, "diff": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Daily change in `value` since the previous data point." }, "weekly_diff": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Change in `value` versus 7 days ago." }, "weekly_diff_percent": { "type": [ "number", "null" ], "format": "float", "description": "Percentage change in `value` versus 7 days ago." }, "monthly_diff": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Change in `value` versus 28 days ago." }, "monthly_diff_percent": { "type": [ "number", "null" ], "format": "float", "description": "Percentage change in `value` versus 28 days ago." }, "daily_diff": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Daily change. Emitted only when `interpolated=true`." }, "interpolated": { "type": [ "boolean", "null" ], "description": "True when this point was synthesized via linear interpolation rather than sourced directly. Not applicable to Spotify popularity." }, "extrapolated": { "type": [ "boolean", "null" ], "description": "True when this point was synthesized via extrapolation past the source-data window." } } }, "description": "Time series of Deezer fan counts." }, "likes": { "type": "array", "items": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Metric value at this timestamp. May arrive as string for some uncast aggregates." }, "timestp": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Timestamp of the data point (ISO 8601)." }, "flags": { "type": [ "boolean", "null" ], "description": "Internal source-data flag for the point." }, "diff": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Daily change in `value` since the previous data point." }, "weekly_diff": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Change in `value` versus 7 days ago." }, "weekly_diff_percent": { "type": [ "number", "null" ], "format": "float", "description": "Percentage change in `value` versus 7 days ago." }, "monthly_diff": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Change in `value` versus 28 days ago." }, "monthly_diff_percent": { "type": [ "number", "null" ], "format": "float", "description": "Percentage change in `value` versus 28 days ago." }, "daily_diff": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Daily change. Emitted only when `interpolated=true`." }, "interpolated": { "type": [ "boolean", "null" ], "description": "True when this point was synthesized via linear interpolation rather than sourced directly. Not applicable to Spotify popularity." }, "extrapolated": { "type": [ "boolean", "null" ], "description": "True when this point was synthesized via extrapolation past the source-data window." } } }, "description": "Time series of platform like counts (Facebook, TikTok)." }, "talks": { "type": "array", "items": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Metric value at this timestamp. May arrive as string for some uncast aggregates." }, "timestp": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Timestamp of the data point (ISO 8601)." }, "flags": { "type": [ "boolean", "null" ], "description": "Internal source-data flag for the point." }, "diff": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Daily change in `value` since the previous data point." }, "weekly_diff": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Change in `value` versus 7 days ago." }, "weekly_diff_percent": { "type": [ "number", "null" ], "format": "float", "description": "Percentage change in `value` versus 7 days ago." }, "monthly_diff": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Change in `value` versus 28 days ago." }, "monthly_diff_percent": { "type": [ "number", "null" ], "format": "float", "description": "Percentage change in `value` versus 28 days ago." }, "daily_diff": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Daily change. Emitted only when `interpolated=true`." }, "interpolated": { "type": [ "boolean", "null" ], "description": "True when this point was synthesized via linear interpolation rather than sourced directly. Not applicable to Spotify popularity." }, "extrapolated": { "type": [ "boolean", "null" ], "description": "True when this point was synthesized via extrapolation past the source-data window." } } }, "description": "Time series of Facebook people-talking-about counts." }, "retweets": { "type": "array", "items": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Metric value at this timestamp. May arrive as string for some uncast aggregates." }, "timestp": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Timestamp of the data point (ISO 8601)." }, "flags": { "type": [ "boolean", "null" ], "description": "Internal source-data flag for the point." }, "diff": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Daily change in `value` since the previous data point." }, "weekly_diff": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Change in `value` versus 7 days ago." }, "weekly_diff_percent": { "type": [ "number", "null" ], "format": "float", "description": "Percentage change in `value` versus 7 days ago." }, "monthly_diff": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Change in `value` versus 28 days ago." }, "monthly_diff_percent": { "type": [ "number", "null" ], "format": "float", "description": "Percentage change in `value` versus 28 days ago." }, "daily_diff": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Daily change. Emitted only when `interpolated=true`." }, "interpolated": { "type": [ "boolean", "null" ], "description": "True when this point was synthesized via linear interpolation rather than sourced directly. Not applicable to Spotify popularity." }, "extrapolated": { "type": [ "boolean", "null" ], "description": "True when this point was synthesized via extrapolation past the source-data window." } } }, "description": "Time series of Twitter/X retweet counts." }, "subscribers": { "type": "array", "items": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Metric value at this timestamp. May arrive as string for some uncast aggregates." }, "timestp": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Timestamp of the data point (ISO 8601)." }, "flags": { "type": [ "boolean", "null" ], "description": "Internal source-data flag for the point." }, "diff": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Daily change in `value` since the previous data point." }, "weekly_diff": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Change in `value` versus 7 days ago." }, "weekly_diff_percent": { "type": [ "number", "null" ], "format": "float", "description": "Percentage change in `value` versus 7 days ago." }, "monthly_diff": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Change in `value` versus 28 days ago." }, "monthly_diff_percent": { "type": [ "number", "null" ], "format": "float", "description": "Percentage change in `value` versus 28 days ago." }, "daily_diff": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Daily change. Emitted only when `interpolated=true`." }, "interpolated": { "type": [ "boolean", "null" ], "description": "True when this point was synthesized via linear interpolation rather than sourced directly. Not applicable to Spotify popularity." }, "extrapolated": { "type": [ "boolean", "null" ], "description": "True when this point was synthesized via extrapolation past the source-data window." } } }, "description": "Time series of YouTube channel subscriber counts." }, "views": { "type": "array", "items": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Metric value at this timestamp. May arrive as string for some uncast aggregates." }, "timestp": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Timestamp of the data point (ISO 8601)." }, "flags": { "type": [ "boolean", "null" ], "description": "Internal source-data flag for the point." }, "diff": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Daily change in `value` since the previous data point." }, "weekly_diff": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Change in `value` versus 7 days ago." }, "weekly_diff_percent": { "type": [ "number", "null" ], "format": "float", "description": "Percentage change in `value` versus 7 days ago." }, "monthly_diff": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Change in `value` versus 28 days ago." }, "monthly_diff_percent": { "type": [ "number", "null" ], "format": "float", "description": "Percentage change in `value` versus 28 days ago." }, "daily_diff": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Daily change. Emitted only when `interpolated=true`." }, "interpolated": { "type": [ "boolean", "null" ], "description": "True when this point was synthesized via linear interpolation rather than sourced directly. Not applicable to Spotify popularity." }, "extrapolated": { "type": [ "boolean", "null" ], "description": "True when this point was synthesized via extrapolation past the source-data window." } } }, "description": "Time series of YouTube channel views or Wikipedia views." }, "videos": { "type": "array", "items": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Metric value at this timestamp. May arrive as string for some uncast aggregates." }, "timestp": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Timestamp of the data point (ISO 8601)." }, "flags": { "type": [ "boolean", "null" ], "description": "Internal source-data flag for the point." }, "diff": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Daily change in `value` since the previous data point." }, "weekly_diff": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Change in `value` versus 7 days ago." }, "weekly_diff_percent": { "type": [ "number", "null" ], "format": "float", "description": "Percentage change in `value` versus 7 days ago." }, "monthly_diff": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Change in `value` versus 28 days ago." }, "monthly_diff_percent": { "type": [ "number", "null" ], "format": "float", "description": "Percentage change in `value` versus 28 days ago." }, "daily_diff": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Daily change. Emitted only when `interpolated=true`." }, "interpolated": { "type": [ "boolean", "null" ], "description": "True when this point was synthesized via linear interpolation rather than sourced directly. Not applicable to Spotify popularity." }, "extrapolated": { "type": [ "boolean", "null" ], "description": "True when this point was synthesized via extrapolation past the source-data window." } } }, "description": "Time series of YouTube video counts." }, "comments": { "type": "array", "items": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Metric value at this timestamp. May arrive as string for some uncast aggregates." }, "timestp": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Timestamp of the data point (ISO 8601)." }, "flags": { "type": [ "boolean", "null" ], "description": "Internal source-data flag for the point." }, "diff": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Daily change in `value` since the previous data point." }, "weekly_diff": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Change in `value` versus 7 days ago." }, "weekly_diff_percent": { "type": [ "number", "null" ], "format": "float", "description": "Percentage change in `value` versus 7 days ago." }, "monthly_diff": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Change in `value` versus 28 days ago." }, "monthly_diff_percent": { "type": [ "number", "null" ], "format": "float", "description": "Percentage change in `value` versus 28 days ago." }, "daily_diff": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Daily change. Emitted only when `interpolated=true`." }, "interpolated": { "type": [ "boolean", "null" ], "description": "True when this point was synthesized via linear interpolation rather than sourced directly. Not applicable to Spotify popularity." }, "extrapolated": { "type": [ "boolean", "null" ], "description": "True when this point was synthesized via extrapolation past the source-data window." } } }, "description": "Time series of YouTube comment counts." }, "daily_views": { "type": "array", "items": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Metric value at this timestamp. May arrive as string for some uncast aggregates." }, "timestp": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Timestamp of the data point (ISO 8601)." }, "flags": { "type": [ "boolean", "null" ], "description": "Internal source-data flag for the point." }, "diff": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Daily change in `value` since the previous data point." }, "weekly_diff": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Change in `value` versus 7 days ago." }, "weekly_diff_percent": { "type": [ "number", "null" ], "format": "float", "description": "Percentage change in `value` versus 7 days ago." }, "monthly_diff": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Change in `value` versus 28 days ago." }, "monthly_diff_percent": { "type": [ "number", "null" ], "format": "float", "description": "Percentage change in `value` versus 28 days ago." }, "daily_diff": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Daily change. Emitted only when `interpolated=true`." }, "interpolated": { "type": [ "boolean", "null" ], "description": "True when this point was synthesized via linear interpolation rather than sourced directly. Not applicable to Spotify popularity." }, "extrapolated": { "type": [ "boolean", "null" ], "description": "True when this point was synthesized via extrapolation past the source-data window." } } }, "description": "Time series of YouTube-for-Artist daily video views." }, "monthly_views": { "type": "array", "items": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Metric value at this timestamp. May arrive as string for some uncast aggregates." }, "timestp": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Timestamp of the data point (ISO 8601)." }, "flags": { "type": [ "boolean", "null" ], "description": "Internal source-data flag for the point." }, "diff": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Daily change in `value` since the previous data point." }, "weekly_diff": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Change in `value` versus 7 days ago." }, "weekly_diff_percent": { "type": [ "number", "null" ], "format": "float", "description": "Percentage change in `value` versus 7 days ago." }, "monthly_diff": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Change in `value` versus 28 days ago." }, "monthly_diff_percent": { "type": [ "number", "null" ], "format": "float", "description": "Percentage change in `value` versus 28 days ago." }, "daily_diff": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Daily change. Emitted only when `interpolated=true`." }, "interpolated": { "type": [ "boolean", "null" ], "description": "True when this point was synthesized via linear interpolation rather than sourced directly. Not applicable to Spotify popularity." }, "extrapolated": { "type": [ "boolean", "null" ], "description": "True when this point was synthesized via extrapolation past the source-data window." } } }, "description": "Time series of YouTube-for-Artist monthly video views." }, "follower_count": { "type": "array", "items": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Metric value at this timestamp. May arrive as string for some uncast aggregates." }, "timestp": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Timestamp of the data point (ISO 8601)." }, "flags": { "type": [ "boolean", "null" ], "description": "Internal source-data flag for the point." }, "diff": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Daily change in `value` since the previous data point." }, "weekly_diff": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Change in `value` versus 7 days ago." }, "weekly_diff_percent": { "type": [ "number", "null" ], "format": "float", "description": "Percentage change in `value` versus 7 days ago." }, "monthly_diff": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Change in `value` versus 28 days ago." }, "monthly_diff_percent": { "type": [ "number", "null" ], "format": "float", "description": "Percentage change in `value` versus 28 days ago." }, "daily_diff": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Daily change. Emitted only when `interpolated=true`." }, "interpolated": { "type": [ "boolean", "null" ], "description": "True when this point was synthesized via linear interpolation rather than sourced directly. Not applicable to Spotify popularity." }, "extrapolated": { "type": [ "boolean", "null" ], "description": "True when this point was synthesized via extrapolation past the source-data window." } } }, "description": "Time series of Twitch follower counts." }, "monthly_viewer_hours": { "type": "array", "items": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Metric value at this timestamp. May arrive as string for some uncast aggregates." }, "timestp": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Timestamp of the data point (ISO 8601)." }, "flags": { "type": [ "boolean", "null" ], "description": "Internal source-data flag for the point." }, "diff": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Daily change in `value` since the previous data point." }, "weekly_diff": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Change in `value` versus 7 days ago." }, "weekly_diff_percent": { "type": [ "number", "null" ], "format": "float", "description": "Percentage change in `value` versus 7 days ago." }, "monthly_diff": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Change in `value` versus 28 days ago." }, "monthly_diff_percent": { "type": [ "number", "null" ], "format": "float", "description": "Percentage change in `value` versus 28 days ago." }, "daily_diff": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Daily change. Emitted only when `interpolated=true`." }, "interpolated": { "type": [ "boolean", "null" ], "description": "True when this point was synthesized via linear interpolation rather than sourced directly. Not applicable to Spotify popularity." }, "extrapolated": { "type": [ "boolean", "null" ], "description": "True when this point was synthesized via extrapolation past the source-data window." } } }, "description": "Time series of Twitch monthly viewer hours." }, "weekly_viewer_hours": { "type": "array", "items": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Metric value at this timestamp. May arrive as string for some uncast aggregates." }, "timestp": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Timestamp of the data point (ISO 8601)." }, "flags": { "type": [ "boolean", "null" ], "description": "Internal source-data flag for the point." }, "diff": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Daily change in `value` since the previous data point." }, "weekly_diff": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Change in `value` versus 7 days ago." }, "weekly_diff_percent": { "type": [ "number", "null" ], "format": "float", "description": "Percentage change in `value` versus 7 days ago." }, "monthly_diff": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Change in `value` versus 28 days ago." }, "monthly_diff_percent": { "type": [ "number", "null" ], "format": "float", "description": "Percentage change in `value` versus 28 days ago." }, "daily_diff": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Daily change. Emitted only when `interpolated=true`." }, "interpolated": { "type": [ "boolean", "null" ], "description": "True when this point was synthesized via linear interpolation rather than sourced directly. Not applicable to Spotify popularity." }, "extrapolated": { "type": [ "boolean", "null" ], "description": "True when this point was synthesized via extrapolation past the source-data window." } } }, "description": "Time series of Twitch weekly viewer hours." }, "artist_likes": { "type": "array", "items": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Metric value at this timestamp. May arrive as string for some uncast aggregates." }, "timestp": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Timestamp of the data point (ISO 8601)." }, "flags": { "type": [ "boolean", "null" ], "description": "Internal source-data flag for the point." }, "diff": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Daily change in `value` since the previous data point." }, "weekly_diff": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Change in `value` versus 7 days ago." }, "weekly_diff_percent": { "type": [ "number", "null" ], "format": "float", "description": "Percentage change in `value` versus 7 days ago." }, "monthly_diff": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Change in `value` versus 28 days ago." }, "monthly_diff_percent": { "type": [ "number", "null" ], "format": "float", "description": "Percentage change in `value` versus 28 days ago." }, "daily_diff": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Daily change. Emitted only when `interpolated=true`." }, "interpolated": { "type": [ "boolean", "null" ], "description": "True when this point was synthesized via linear interpolation rather than sourced directly. Not applicable to Spotify popularity." }, "extrapolated": { "type": [ "boolean", "null" ], "description": "True when this point was synthesized via extrapolation past the source-data window." } } }, "description": "Time series of Line Music artist-like counts." } } } }, "additionalProperties": false }, "examples": { "default": { "value": { "obj": { "link": "https://open.spotify.com/artist/4gzpq5DPGxSnKTe4SA8HAU", "followers": [ { "weekly_diff": 100339, "weekly_diff_percent": 0.3637, "monthly_diff": 343512, "monthly_diff_percent": 1.2562, "value": 23806554, "timestp": "2020-01-03T08:00:00.000Z", "diff": 17652 } ], "popularity": [ { "weekly_diff": 0, "weekly_diff_percent": 0, "monthly_diff": 1, "monthly_diff_percent": 1.1236, "value": 93, "timestp": "2020-01-01T08:00:00.000Z" } ], "listeners": [ { "weekly_diff": -239091, "weekly_diff_percent": -0.6747, "monthly_diff": 343076, "monthly_diff_percent": 0.9843, "value": 41400238, "timestp": "2020-01-01T08:00:00.000Z", "diff": null } ], "followers_to_listeners_ratio": [ { "weekly_diff": 0.008138, "weekly_diff_percent": 1.0453, "monthly_diff": 0.002112, "monthly_diff_percent": 0.2692, "value": "57.41", "timestp": "2020-01-01T08:00:00.000Z" } ] } } } } } } } } } }, "/api/artist/{id}/instagram-audience-stats": { "get": { "summary": "💎 Premium — Instagram Audience Stats", "tags": [ "Artist" ], "operationId": "getArtistInstagramAudienceStats", "description": "Instagram audience analysis for an artist (latest report or historical via `date`). Geo breakdown (top countries / cities for both followers and likers), gender/age + ethnicity + brand affinity + interest rollups for followers and likers, plus engagement metrics (`followers`, `avg_likes_per_post`, `avg_comments_per_post`, `engagement_rate`) and notable followers. Pass `geoOnly=true` to drop demographic rollups and notable followers. Dates for which data is available are listed at `/api/artist/{id}/instagram-audience-stats/dates`. The response also carries the misspelled `avg_commments_per_post` with the same value; it is removed after October 1st, 2026. The vendor panel behind the liker breakdowns, the brand / interest rollups and `notable_followers` was retired — those keys stay in the response but stop updating from October 1st, 2026, carrying the last values collected from the panel or an empty array where none were.\n\nBrand and influencer categories with the highest affinities cover related ground but are not a like-for-like replacement: audience interests measured the categories an artist's own followers engaged with, while the new categories measure similarity to profiles with a comparable audience.", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer", "minimum": 2, "maximum": 2147483647, "not": { "enum": [ 1 ] }, "description": "Chartmetric artist ID. Note: id=1 ('Various Artists') is rejected." }, "required": true, "description": "Chartmetric artist ID. Note: id=1 ('Various Artists') is rejected.", "examples": { "default": { "value": 2 } } }, { "name": "date", "in": "query", "schema": { "type": "string", "format": "date", "description": "Historical date (`YYYY-MM-DD`). When omitted, returns the most recent available report. Use the dates endpoint to discover available dates." }, "required": false, "description": "Historical date (`YYYY-MM-DD`). When omitted, returns the most recent available report. Use the dates endpoint to discover available dates." }, { "name": "geoOnly", "in": "query", "schema": { "type": "boolean", "description": "If true, drop demographic / brand-affinity / interest / notable-followers blocks and return only geo + engagement counters.", "default": false }, "required": false, "description": "If true, drop demographic / brand-affinity / interest / notable-followers blocks and return only geo + engagement counters." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "object", "properties": { "top_countries": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "description": "Country name." }, "code": { "type": [ "string", "null" ], "description": "Lower-cased country code (ISO 3166-1 alpha-2)." }, "percent": { "type": [ "string", "null" ], "description": "Audience share for the country, as a percent string with 2 decimals." }, "followers": { "type": [ "integer", "null" ], "description": "Number of audience followers in this country." }, "subscribers": { "type": [ "integer", "null" ], "description": "Number of audience subscribers in this country (YouTube)." }, "likes": { "type": [ "integer", "null" ], "description": "Number of audience likes attributable to this country." }, "comments": { "type": [ "integer", "null" ], "description": "Number of audience comments from this country (YouTube commenters)." } } }, "description": "Top countries among the artist's Instagram followers." }, "top_cities": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "description": "City name." }, "state": { "type": [ "string", "null" ], "description": "State/region name." }, "country": { "type": [ "string", "null" ], "description": "Country name." }, "percent": { "type": [ "string", "null" ], "description": "Audience share for the city, as a percent string with 2 decimals." }, "followers": { "type": [ "integer", "null" ], "description": "Number of audience followers in this city." }, "likes": { "type": [ "integer", "null" ], "description": "Number of audience likes attributable to this city." } } }, "description": "Top cities among the artist's Instagram followers." }, "likers_top_countries": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "description": "Country name." }, "code": { "type": [ "string", "null" ], "description": "Lower-cased country code (ISO 3166-1 alpha-2)." }, "percent": { "type": [ "string", "null" ], "description": "Audience share for the country, as a percent string with 2 decimals." }, "followers": { "type": [ "integer", "null" ], "description": "Number of audience followers in this country." }, "subscribers": { "type": [ "integer", "null" ], "description": "Number of audience subscribers in this country (YouTube)." }, "likes": { "type": [ "integer", "null" ], "description": "Number of audience likes attributable to this country." }, "comments": { "type": [ "integer", "null" ], "description": "Number of audience comments from this country (YouTube commenters)." } } }, "description": "Top countries among the artist's Instagram likers. Deprecated effective October 1st, 2026 — no longer updated. The key stays in the response, carrying either the last values collected from the retired panel or an empty array for accounts that never had them.", "deprecated": true }, "likers_top_cities": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "description": "City name." }, "state": { "type": [ "string", "null" ], "description": "State/region name." }, "country": { "type": [ "string", "null" ], "description": "Country name." }, "percent": { "type": [ "string", "null" ], "description": "Audience share for the city, as a percent string with 2 decimals." }, "followers": { "type": [ "integer", "null" ], "description": "Number of audience followers in this city." }, "likes": { "type": [ "integer", "null" ], "description": "Number of audience likes attributable to this city." } } }, "description": "Top cities among the artist's Instagram likers. Deprecated effective October 1st, 2026 — no longer updated. The key stays in the response, carrying either the last values collected from the retired panel or an empty array for accounts that never had them.", "deprecated": true }, "audience_genders_per_age": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": [ "string", "null" ], "description": "Age bucket code (e.g. `13-17`, `18-24`, `25-34`)." }, "male": { "type": [ "string", "null" ], "description": "Male share for the age bucket, as a percent string." }, "female": { "type": [ "string", "null" ], "description": "Female share for the age bucket, as a percent string." } } }, "description": "Follower gender share per age bucket." }, "audience_ethnicities": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": [ "string", "null" ], "description": "Ethnicity code." }, "name": { "type": [ "string", "null" ], "description": "Ethnicity display name." }, "weight": { "type": [ "string", "null" ], "description": "Audience share for the ethnicity, as a percent string." } } }, "description": "Follower ethnicity rollup." }, "audience_genders": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": [ "string", "null" ], "description": "Gender code (`male` or `female`); may surface uppercase for some YouTube rollups." }, "weight": { "type": [ "string", "null" ], "description": "Audience share for the gender, as a percent string." } } }, "description": "Follower gender rollup." }, "audience_brand_affinities": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "description": "Brand or interest display name." }, "weight": { "type": [ "string", "null" ], "description": "Audience share for the brand/interest, as a percent string." }, "affinity": { "type": [ "number", "null" ], "format": "float", "description": "Audience affinity score for the brand/interest." } } }, "description": "Follower brand affinity rollup. Deprecated effective October 1st, 2026 — no longer updated. The key stays in the response, carrying either the last values collected from the retired panel or an empty array for accounts that never had them.", "deprecated": true }, "audience_interests": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "description": "Brand or interest display name." }, "weight": { "type": [ "string", "null" ], "description": "Audience share for the brand/interest, as a percent string." }, "affinity": { "type": [ "number", "null" ], "format": "float", "description": "Audience affinity score for the brand/interest." } } }, "description": "Follower interest rollup. Deprecated effective October 1st, 2026 — no longer updated. The key stays in the response, carrying either the last values collected from the retired panel or an empty array for accounts that never had them.", "deprecated": true }, "audience_likers_genders_per_age": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": [ "string", "null" ], "description": "Age bucket code (e.g. `13-17`, `18-24`, `25-34`)." }, "male": { "type": [ "string", "null" ], "description": "Male share for the age bucket, as a percent string." }, "female": { "type": [ "string", "null" ], "description": "Female share for the age bucket, as a percent string." } } }, "description": "Liker gender share per age bucket. Deprecated effective October 1st, 2026 — no longer updated. The key stays in the response, carrying either the last values collected from the retired panel or an empty array for accounts that never had them.", "deprecated": true }, "audience_likers_ethnicities": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": [ "string", "null" ], "description": "Ethnicity code." }, "name": { "type": [ "string", "null" ], "description": "Ethnicity display name." }, "weight": { "type": [ "string", "null" ], "description": "Audience share for the ethnicity, as a percent string." } } }, "description": "Liker ethnicity rollup. Deprecated effective October 1st, 2026 — no longer updated. The key stays in the response, carrying either the last values collected from the retired panel or an empty array for accounts that never had them.", "deprecated": true }, "audience_likers_genders": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": [ "string", "null" ], "description": "Gender code (`male` or `female`); may surface uppercase for some YouTube rollups." }, "weight": { "type": [ "string", "null" ], "description": "Audience share for the gender, as a percent string." } } }, "description": "Liker gender rollup. Deprecated effective October 1st, 2026 — no longer updated. The key stays in the response, carrying either the last values collected from the retired panel or an empty array for accounts that never had them.", "deprecated": true }, "audience_likers_brand_affinities": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "description": "Brand or interest display name." }, "weight": { "type": [ "string", "null" ], "description": "Audience share for the brand/interest, as a percent string." }, "affinity": { "type": [ "number", "null" ], "format": "float", "description": "Audience affinity score for the brand/interest." } } }, "description": "Liker brand affinity rollup. Deprecated effective October 1st, 2026 — no longer updated. The key stays in the response, carrying either the last values collected from the retired panel or an empty array for accounts that never had them.", "deprecated": true }, "audience_likers_interests": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "description": "Brand or interest display name." }, "weight": { "type": [ "string", "null" ], "description": "Audience share for the brand/interest, as a percent string." }, "affinity": { "type": [ "number", "null" ], "format": "float", "description": "Audience affinity score for the brand/interest." } } }, "description": "Liker interest rollup. Deprecated effective October 1st, 2026 — no longer updated. The key stays in the response, carrying either the last values collected from the retired panel or an empty array for accounts that never had them.", "deprecated": true }, "notable_followers": { "type": "array", "items": { "type": "object", "properties": { "user_id": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Platform-native user ID of the notable follower." }, "username": { "type": [ "string", "null" ], "description": "Username on the platform." }, "custom_name": { "type": [ "string", "null" ], "description": "YouTube custom channel name." }, "handle": { "type": [ "string", "null" ], "description": "YouTube channel handle." }, "picture": { "type": [ "string", "null" ], "description": "Profile picture URL." }, "fullname": { "type": [ "string", "null" ], "description": "Display / full name." }, "url": { "type": [ "string", "null" ], "description": "Profile URL." }, "followers": { "type": [ "integer", "null" ], "description": "Follower count of the notable user (Instagram, TikTok)." }, "subscribers": { "type": [ "integer", "null" ], "description": "Subscriber count of the notable user (YouTube)." }, "is_verified": { "anyOf": [ { "type": "boolean" }, { "type": "string" } ], "nullable": true, "description": "True when the user is platform-verified." }, "engagements": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "User's engagement metric on the platform." }, "avg_likes": { "type": [ "integer", "null" ], "description": "Average likes per post (YouTube)." }, "avg_views": { "type": [ "integer", "null" ], "description": "Average views per video (YouTube)." }, "geo": { "type": [ "object", "null" ], "properties": { "country": { "type": [ "object", "null" ], "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Identifier of the geo level (country / state / city)." }, "name": { "type": [ "string", "null" ], "description": "Display name of the geo level." }, "code": { "type": [ "string", "null" ], "description": "Code of the geo level (e.g. ISO country code)." }, "coords": { "type": [ "object", "null" ], "properties": { "lat": { "type": [ "number", "null" ], "format": "float", "description": "Latitude." }, "lon": { "type": [ "number", "null" ], "format": "float", "description": "Longitude." } }, "description": "Geographic coordinates of the geo level." } }, "description": "Geo level (country / state / city) with id, name, code, and coordinates." }, "state": { "type": [ "object", "null" ], "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Identifier of the geo level (country / state / city)." }, "name": { "type": [ "string", "null" ], "description": "Display name of the geo level." }, "code": { "type": [ "string", "null" ], "description": "Code of the geo level (e.g. ISO country code)." }, "coords": { "type": [ "object", "null" ], "properties": { "lat": { "type": [ "number", "null" ], "format": "float", "description": "Latitude." }, "lon": { "type": [ "number", "null" ], "format": "float", "description": "Longitude." } }, "description": "Geographic coordinates of the geo level." } }, "description": "Geo level (country / state / city) with id, name, code, and coordinates." }, "city": { "type": [ "object", "null" ], "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Identifier of the geo level (country / state / city)." }, "name": { "type": [ "string", "null" ], "description": "Display name of the geo level." }, "code": { "type": [ "string", "null" ], "description": "Code of the geo level (e.g. ISO country code)." }, "coords": { "type": [ "object", "null" ], "properties": { "lat": { "type": [ "number", "null" ], "format": "float", "description": "Latitude." }, "lon": { "type": [ "number", "null" ], "format": "float", "description": "Longitude." } }, "description": "Geographic coordinates of the geo level." } }, "description": "Geo level (country / state / city) with id, name, code, and coordinates." } }, "description": "Geo location of the user. Each level (`country`, `state`, `city`) carries `{id, name, code, coords:{lat,lon}}`; absent levels are `null` or `{}`. Population varies by platform." } } }, "description": "Notable followers of the artist's Instagram account. Deprecated effective October 1st, 2026 — no longer updated. The key stays in the response, carrying either the last values collected from the retired panel or an empty array for accounts that never had them.", "deprecated": true }, "followers": { "type": [ "integer", "null" ], "description": "Total Instagram follower count for the artist." }, "avg_likes_per_post": { "type": [ "integer", "null" ], "description": "Average likes per post." }, "avg_commments_per_post": { "type": [ "integer", "null" ], "description": "Average comments per post. Deprecated — this misspelling is removed after October 1st, 2026; use `avg_comments_per_post`.", "deprecated": true }, "avg_comments_per_post": { "type": [ "integer", "null" ], "description": "Average comments per post." }, "engagement_rate": { "type": [ "number", "null" ], "format": "float", "description": "Engagement rate as a 0–1 ratio." }, "timestp": { "type": [ "string", "null" ], "description": "Date of the retrieved data (ISO YYYY-MM-DD string)." } } } }, "additionalProperties": false }, "examples": { "default": { "value": { "obj": { "top_countries": [ { "name": "United States", "code": "us", "percent": "24.79", "followers": 7661481 } ], "top_cities": [ { "name": "New York City", "state": "New York", "country": "United States", "percent": "1.57", "followers": 486692 } ], "likers_top_countries": [ { "name": "Indonesia", "code": "id", "percent": "23.94", "likes": 881672709 } ], "likers_top_cities": [ { "name": "Jakarta", "country": "Indonesia", "percent": "1.53", "likes": 56389121 } ], "audience_genders": [ { "code": "male", "weight": "64.81" }, { "code": "female", "weight": "35.19" } ], "followers": 30905034, "avg_likes_per_post": 716758, "avg_commments_per_post": 7136, "avg_comments_per_post": 7136, "engagement_rate": 2.3423, "timestp": "2022-04-03" } } } } } } } } } }, "/api/artist/{id}/instagram-audience-stats/dates": { "get": { "summary": "💎 Premium — Instagram Audience Stats Available Dates", "tags": [ "Artist" ], "operationId": "listArtistInstagramAudienceStatsDates", "description": "Dates (YYYY-MM-DD) for which Instagram audience analysis is available for the artist. Use these values as the `date` parameter on `/api/artist/{id}/instagram-audience-stats` to avoid empty responses. Returns 404 when the artist has no linked Instagram account.", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer", "minimum": 2, "maximum": 2147483647, "not": { "enum": [ 1 ] }, "description": "Chartmetric artist ID. Note: id=1 ('Various Artists') is rejected." }, "required": true, "description": "Chartmetric artist ID. Note: id=1 ('Various Artists') is rejected.", "examples": { "default": { "value": 2 } } }, { "name": "date", "in": "query", "schema": { "type": "string", "format": "date", "description": "Historical date (`YYYY-MM-DD`). When omitted, returns the most recent available report. Use the dates endpoint to discover available dates." }, "required": false, "description": "Historical date (`YYYY-MM-DD`). When omitted, returns the most recent available report. Use the dates endpoint to discover available dates." }, { "name": "geoOnly", "in": "query", "schema": { "type": "boolean", "description": "If true, drop demographic / brand-affinity / interest / notable-followers blocks and return only geo + engagement counters.", "default": false }, "required": false, "description": "If true, drop demographic / brand-affinity / interest / notable-followers blocks and return only geo + engagement counters." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "object", "properties": { "dates": { "type": "array", "items": { "type": [ "string", "null" ] }, "description": "Available report dates in ISO `YYYY-MM-DD` format, sorted descending." } }, "required": [ "dates" ] } }, "additionalProperties": false }, "examples": { "default": { "value": { "obj": { "dates": [ "2022-09-12", "2022-09-11" ] } } } } } } } } } }, "/api/artist/{id}/social-audience-stats": { "get": { "summary": "💎 Premium — Social Audience Stats Time Series", "tags": [ "Artist" ], "operationId": "getArtistSocialAudienceStats", "description": "Time-series of Instagram / TikTok / YouTube audience stats. Pass `domain` (`instagram`, `tiktok`, `youtube`), `audienceType` (`followers`, `likes`, `commenters`), and `statsType` (`stat`, `demographic`, `country`, `city`, `language`, `brand`, `interest`) plus `since` / `until`. Each item's keys depend on the requested `statsType` — e.g. `stat` rows carry engagement counters, `country` rows carry `code2` + `rank` + `weights`, `city` rows add `city_id` + `city_name` + `city_affinity`. Data is daily historical and may differ slightly from the web app's near-real-time view.", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer", "minimum": 2, "maximum": 2147483647, "not": { "enum": [ 1 ] }, "description": "Chartmetric artist ID. Note: id=1 ('Various Artists') is rejected." }, "required": true, "description": "Chartmetric artist ID. Note: id=1 ('Various Artists') is rejected.", "examples": { "default": { "value": 2 } } }, { "name": "domain", "in": "query", "schema": { "type": "string", "enum": [ "instagram", "youtube", "tiktok" ], "description": "Social platform. One of `instagram`, `youtube`, `tiktok`. Different platforms support different `audienceType` and `statsType` combinations." }, "required": true, "description": "Social platform. One of `instagram`, `youtube`, `tiktok`. Different platforms support different `audienceType` and `statsType` combinations.", "examples": { "default": { "value": "instagram" } } }, { "name": "audienceType", "in": "query", "schema": { "type": "string", "description": "Audience subset. One of `followers`, `likes`, `commenters`. Valid combinations with `domain` are platform-specific." }, "required": true, "description": "Audience subset. One of `followers`, `likes`, `commenters`. Valid combinations with `domain` are platform-specific.", "examples": { "default": { "value": "example" } } }, { "name": "statsType", "in": "query", "schema": { "type": "string", "description": "Audience metric kind. One of `country`, `city`, `interest`, `brand`, `language`, `stat`, `demographic`. Valid combinations with `domain` are platform-specific." }, "required": true, "description": "Audience metric kind. One of `country`, `city`, `interest`, `brand`, `language`, `stat`, `demographic`. Valid combinations with `domain` are platform-specific.", "examples": { "default": { "value": "example" } } }, { "name": "since", "in": "query", "schema": { "type": "string", "format": "date", "description": "Start of the date window in ISO format (e.g. '2025-11-01'). Defaults to today.", "default": "2026-11-05" }, "required": false, "description": "Start of the date window in ISO format (e.g. '2025-11-01'). Defaults to today." }, { "name": "until", "in": "query", "schema": { "type": "string", "format": "date", "description": "End of the date window in ISO format (e.g. '2025-11-15'). Defaults to today.", "default": "2026-11-05" }, "required": false, "description": "End of the date window in ISO format (e.g. '2025-11-15'). Defaults to today." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, "required": false, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Maximum number of entries to return. Defaults to 50, max 100.", "default": 50 }, "required": false, "description": "Maximum number of entries to return. Defaults to 50, max 100." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "array", "items": { "type": "object", "properties": { "timestp": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Date of the data point (ISO 8601)." }, "followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Follower count (or subscriber count for YouTube). Present in `stat` rows." }, "avg_likes_per_post": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Average likes per post. Present in `stat` rows." }, "avg_comments_per_post": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Average comments per post. Present in `stat` rows." }, "avg_views_per_post": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Average views per post. Present in `stat` rows (TikTok, YouTube)." }, "engagement_rate": { "type": [ "number", "null" ], "format": "float", "description": "Engagement rate as a 0–1 ratio. Present in `stat` rows." }, "code2": { "type": [ "string", "null" ], "description": "Country code (ISO 3166-1 alpha-2). Present in `country`/`city` rows." }, "rank": { "type": [ "integer", "null" ], "description": "Rank of the location relative to all locations." }, "weights": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Audience-share weight for the location." }, "name": { "type": [ "string", "null" ], "description": "Country or location name." }, "lat": { "type": [ "number", "null" ], "format": "float", "description": "Latitude (city/country rows)." }, "lng": { "type": [ "number", "null" ], "format": "float", "description": "Longitude (city/country rows)." }, "city_id": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 2147483647 }, { "type": "string" } ], "nullable": true, "description": "Chartmetric city ID. Present in `city` rows." }, "city_name": { "type": [ "string", "null" ], "description": "City display name. Present in `city` rows." }, "city_affinity": { "type": [ "number", "null" ], "format": "float", "description": "Audience affinity score for the city." }, "value": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Audience metric value (denomination depends on `statsType`)." }, "language_name": { "type": [ "string", "null" ], "description": "Language display name. Present in `language` rows." }, "brand_id": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 2147483647 }, { "type": "string" } ], "nullable": true, "description": "Chartmetric brand ID. Present in `brand` rows." }, "brand_name": { "type": [ "string", "null" ], "description": "Brand display name." }, "brand_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Number of artist audience followers also following the brand." }, "interest_id": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 2147483647 }, { "type": "string" } ], "nullable": true, "description": "Chartmetric interest ID. Present in `interest` rows." }, "interest_name": { "type": [ "string", "null" ], "description": "Interest display name." }, "interest_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Number of artist audience followers also following the interest." }, "weight": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Audience-share weight for the brand/interest/language row." }, "scale": { "type": [ "number", "null" ], "format": "float", "description": "Audience affinity scale for brands/interests." } } } } }, "required": [ "obj" ], "additionalProperties": false }, "examples": { "default": { "value": { "obj": [ { "timestp": "2021-09-15", "followers": 266129565, "avg_likes_per_post": 4611034, "avg_comments_per_post": 25014, "avg_views_per_post": 7397898, "engagement_rate": 1.742 } ] } } } } } } } } }, "/api/artist/{id}/youtube-audience-stats": { "get": { "summary": "💎 Premium — YouTube Audience Stats", "tags": [ "Artist" ], "operationId": "getArtistYoutubeAudienceStats", "description": "YouTube audience analysis for an artist (latest report or historical via `date`). Geo breakdown (top subscribing + commenting countries), gender/age demographics for subscribers and commenters, plus engagement counters (`subscribers`, `avg_likes_per_post`, `avg_comments_per_post`, `engagement_rate`). Pass `geoOnly=true` to drop demographic arrays and notable subscribers. Returns a stable shape even when the artist has no linked YouTube channel (arrays empty, counters `null`/`undefined`). The response also carries the misspelled `avg_commments_per_post` with the same value; it is removed after October 1st, 2026. The vendor panel behind `notable_subscribers` and the commenter breakdowns was retired — those keys stay in the response but stop updating from October 1st, 2026, carrying the last values collected from the panel or an empty array where none were.", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer", "minimum": 2, "maximum": 2147483647, "not": { "enum": [ 1 ] }, "description": "Chartmetric artist ID. Note: id=1 ('Various Artists') is rejected." }, "required": true, "description": "Chartmetric artist ID. Note: id=1 ('Various Artists') is rejected.", "examples": { "default": { "value": 2 } } }, { "name": "date", "in": "query", "schema": { "type": "string", "format": "date", "description": "Historical date (`YYYY-MM-DD`). When omitted, returns the most recent available report. Use the dates endpoint to discover available dates." }, "required": false, "description": "Historical date (`YYYY-MM-DD`). When omitted, returns the most recent available report. Use the dates endpoint to discover available dates." }, { "name": "geoOnly", "in": "query", "schema": { "type": "boolean", "description": "If true, drop demographic / brand-affinity / interest / notable-followers blocks and return only geo + engagement counters.", "default": false }, "required": false, "description": "If true, drop demographic / brand-affinity / interest / notable-followers blocks and return only geo + engagement counters." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "object", "properties": { "top_countries": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "description": "Country name." }, "code": { "type": [ "string", "null" ], "description": "Lower-cased country code (ISO 3166-1 alpha-2)." }, "percent": { "type": [ "string", "null" ], "description": "Audience share for the country, as a percent string with 2 decimals." }, "followers": { "type": [ "integer", "null" ], "description": "Number of audience followers in this country." }, "subscribers": { "type": [ "integer", "null" ], "description": "Number of audience subscribers in this country (YouTube)." }, "likes": { "type": [ "integer", "null" ], "description": "Number of audience likes attributable to this country." }, "comments": { "type": [ "integer", "null" ], "description": "Number of audience comments from this country (YouTube commenters)." } } }, "description": "Top countries among the artist's YouTube subscribers." }, "commenters_top_countries": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "description": "Country name." }, "code": { "type": [ "string", "null" ], "description": "Lower-cased country code (ISO 3166-1 alpha-2)." }, "percent": { "type": [ "string", "null" ], "description": "Audience share for the country, as a percent string with 2 decimals." }, "followers": { "type": [ "integer", "null" ], "description": "Number of audience followers in this country." }, "subscribers": { "type": [ "integer", "null" ], "description": "Number of audience subscribers in this country (YouTube)." }, "likes": { "type": [ "integer", "null" ], "description": "Number of audience likes attributable to this country." }, "comments": { "type": [ "integer", "null" ], "description": "Number of audience comments from this country (YouTube commenters)." } } }, "description": "Top countries among the artist's YouTube commenters. Deprecated effective October 1st, 2026 — no longer updated. The key stays in the response, carrying either the last values collected from the retired panel or an empty array for accounts that never had them.", "deprecated": true }, "audience_genders_per_age": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": [ "string", "null" ], "description": "Age bucket code (e.g. `13-17`, `18-24`, `25-34`)." }, "male": { "type": [ "string", "null" ], "description": "Male share for the age bucket, as a percent string." }, "female": { "type": [ "string", "null" ], "description": "Female share for the age bucket, as a percent string." } } }, "description": "Subscriber gender share per age bucket." }, "audience_genders": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": [ "string", "null" ], "description": "Gender code (`male` or `female`); may surface uppercase for some YouTube rollups." }, "weight": { "type": [ "string", "null" ], "description": "Audience share for the gender, as a percent string." } } }, "description": "Subscriber gender rollup." }, "commenters_genders_per_age": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": [ "string", "null" ], "description": "Age bucket code (e.g. `13-17`, `18-24`, `25-34`)." }, "male": { "type": [ "string", "null" ], "description": "Male share for the age bucket, as a percent string." }, "female": { "type": [ "string", "null" ], "description": "Female share for the age bucket, as a percent string." } } }, "description": "Commenter gender share per age bucket. Deprecated effective October 1st, 2026 — no longer updated. The key stays in the response, carrying either the last values collected from the retired panel or an empty array for accounts that never had them.", "deprecated": true }, "commenters_genders": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": [ "string", "null" ], "description": "Gender code (`male` or `female`); may surface uppercase for some YouTube rollups." }, "weight": { "type": [ "string", "null" ], "description": "Audience share for the gender, as a percent string." } } }, "description": "Commenter gender rollup. Deprecated effective October 1st, 2026 — no longer updated. The key stays in the response, carrying either the last values collected from the retired panel or an empty array for accounts that never had them.", "deprecated": true }, "notable_subscribers": { "type": "array", "items": { "type": "object", "properties": { "user_id": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Platform-native user ID of the notable follower." }, "username": { "type": [ "string", "null" ], "description": "Username on the platform." }, "custom_name": { "type": [ "string", "null" ], "description": "YouTube custom channel name." }, "handle": { "type": [ "string", "null" ], "description": "YouTube channel handle." }, "picture": { "type": [ "string", "null" ], "description": "Profile picture URL." }, "fullname": { "type": [ "string", "null" ], "description": "Display / full name." }, "url": { "type": [ "string", "null" ], "description": "Profile URL." }, "followers": { "type": [ "integer", "null" ], "description": "Follower count of the notable user (Instagram, TikTok)." }, "subscribers": { "type": [ "integer", "null" ], "description": "Subscriber count of the notable user (YouTube)." }, "is_verified": { "anyOf": [ { "type": "boolean" }, { "type": "string" } ], "nullable": true, "description": "True when the user is platform-verified." }, "engagements": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "User's engagement metric on the platform." }, "avg_likes": { "type": [ "integer", "null" ], "description": "Average likes per post (YouTube)." }, "avg_views": { "type": [ "integer", "null" ], "description": "Average views per video (YouTube)." }, "geo": { "type": [ "object", "null" ], "properties": { "country": { "type": [ "object", "null" ], "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Identifier of the geo level (country / state / city)." }, "name": { "type": [ "string", "null" ], "description": "Display name of the geo level." }, "code": { "type": [ "string", "null" ], "description": "Code of the geo level (e.g. ISO country code)." }, "coords": { "type": [ "object", "null" ], "properties": { "lat": { "type": [ "number", "null" ], "format": "float", "description": "Latitude." }, "lon": { "type": [ "number", "null" ], "format": "float", "description": "Longitude." } }, "description": "Geographic coordinates of the geo level." } }, "description": "Geo level (country / state / city) with id, name, code, and coordinates." }, "state": { "type": [ "object", "null" ], "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Identifier of the geo level (country / state / city)." }, "name": { "type": [ "string", "null" ], "description": "Display name of the geo level." }, "code": { "type": [ "string", "null" ], "description": "Code of the geo level (e.g. ISO country code)." }, "coords": { "type": [ "object", "null" ], "properties": { "lat": { "type": [ "number", "null" ], "format": "float", "description": "Latitude." }, "lon": { "type": [ "number", "null" ], "format": "float", "description": "Longitude." } }, "description": "Geographic coordinates of the geo level." } }, "description": "Geo level (country / state / city) with id, name, code, and coordinates." }, "city": { "type": [ "object", "null" ], "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Identifier of the geo level (country / state / city)." }, "name": { "type": [ "string", "null" ], "description": "Display name of the geo level." }, "code": { "type": [ "string", "null" ], "description": "Code of the geo level (e.g. ISO country code)." }, "coords": { "type": [ "object", "null" ], "properties": { "lat": { "type": [ "number", "null" ], "format": "float", "description": "Latitude." }, "lon": { "type": [ "number", "null" ], "format": "float", "description": "Longitude." } }, "description": "Geographic coordinates of the geo level." } }, "description": "Geo level (country / state / city) with id, name, code, and coordinates." } }, "description": "Geo location of the user. Each level (`country`, `state`, `city`) carries `{id, name, code, coords:{lat,lon}}`; absent levels are `null` or `{}`. Population varies by platform." } } }, "description": "Notable subscribers of the YouTube channel. Deprecated effective October 1st, 2026 — no longer updated. The key stays in the response, carrying either the last values collected from the retired panel or an empty array for accounts that never had them.", "deprecated": true }, "subscribers": { "type": [ "integer", "null" ], "description": "Total YouTube subscriber count for the artist." }, "avg_likes_per_post": { "type": [ "integer", "null" ], "description": "Average likes per video." }, "avg_commments_per_post": { "type": [ "integer", "null" ], "description": "Average comments per video. Deprecated — this misspelling is removed after October 1st, 2026; use `avg_comments_per_post`.", "deprecated": true }, "avg_comments_per_post": { "type": [ "integer", "null" ], "description": "Average comments per video." }, "engagement_rate": { "type": [ "number", "null" ], "format": "float", "description": "Engagement rate as a 0–1 ratio." }, "last_updated_timestamp": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Date the underlying data was last refreshed (ISO 8601)." }, "timestp": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Date of the retrieved data (ISO 8601)." } } } }, "additionalProperties": false }, "examples": { "default": { "value": { "obj": { "top_countries": [ { "name": "United States", "code": "us", "percent": "20.22", "subscribers": 8675495 } ], "commenters_top_countries": [ { "name": "United States", "code": "us", "percent": "12.53", "comments": 2010886 } ], "audience_genders": [ { "code": "female", "weight": "27.61" }, { "code": "male", "weight": "72.39" } ], "subscribers": 42900000, "avg_likes_per_post": 112574, "avg_commments_per_post": 5679, "avg_comments_per_post": 5679, "engagement_rate": 0.2624, "timestp": "2022-03-28" } } } } } } } } } }, "/api/artist/{id}/tiktok-top-videos": { "get": { "summary": "💎 Premium — List Top TikTok Videos for an Artist", "tags": [ "Artist" ], "operationId": "listArtistTikTokTopVideos", "description": "Top TikTok videos using any of the artist's sounds. Takes the same paging and filter params as the track route, and each row carries `track_name` so a caller can tell which of the artist's tracks a video used. Page with `limit` and `offset`, narrow with `postedWithinDaysAgo` or the `min`/`max` metric bounds, and set `withTotal=true` to receive the rows inside an envelope carrying `total` and `available_count` rather than as a bare array.", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer", "minimum": 2, "maximum": 2147483647, "not": { "enum": [ 1 ] }, "description": "Chartmetric artist ID. Note: id=1 ('Various Artists') is rejected." }, "required": true, "description": "Chartmetric artist ID. Note: id=1 ('Various Artists') is rejected.", "examples": { "default": { "value": 2 } } }, { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "likes", "views", "comments", "followers", "created_at", "trending", "modified_at", "saves", "shares" ], "description": "Sort metric for the returned videos. Defaults to `likes`; allowed values come from TikTok engagement stats.", "default": "likes" }, "required": false, "description": "Sort metric for the returned videos. Defaults to `likes`; allowed values come from TikTok engagement stats." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum number of videos to return. Max 100.", "default": 10 }, "required": false, "description": "Maximum number of videos to return. Max 100." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Number of videos to skip from the start of the result set, for paging past the first `limit` rows. Defaults to 0, max 10,000." }, "required": false, "description": "Number of videos to skip from the start of the result set, for paging past the first `limit` rows. Defaults to 0, max 10,000." }, { "name": "sortOrderDesc", "in": "query", "schema": { "type": "boolean", "description": "Sort direction for `type`. Defaults to true (highest first).", "default": true }, "required": false, "description": "Sort direction for `type`. Defaults to true (highest first)." }, { "name": "withTotal", "in": "query", "schema": { "type": "boolean", "description": "If true, wrap the videos in an object carrying `total` and `available_count` so a caller can page to the end. Defaults to false, which returns the bare array.", "default": false }, "required": false, "description": "If true, wrap the videos in an object carrying `total` and `available_count` so a caller can page to the end. Defaults to false, which returns the bare array." }, { "name": "postedWithinDaysAgo", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Only return videos posted within this many days. Omit to cover all time." }, "required": false, "description": "Only return videos posted within this many days. Omit to cover all time." }, { "name": "fromDaysAgo", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 365, "description": "Window in days used as the baseline for the change-rate fields. Defaults to 28, max 365.", "default": 28 }, "required": false, "description": "Window in days used as the baseline for the change-rate fields. Defaults to 28, max 365." }, { "name": "minViews", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Only return videos with at least this many views." }, "required": false, "description": "Only return videos with at least this many views." }, { "name": "maxViews", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Only return videos with at most this many views." }, "required": false, "description": "Only return videos with at most this many views." }, { "name": "minLikes", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Only return videos with at least this many likes." }, "required": false, "description": "Only return videos with at least this many likes." }, { "name": "maxLikes", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Only return videos with at most this many likes." }, "required": false, "description": "Only return videos with at most this many likes." }, { "name": "minComments", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Only return videos with at least this many comments." }, "required": false, "description": "Only return videos with at least this many comments." }, { "name": "maxComments", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Only return videos with at most this many comments." }, "required": false, "description": "Only return videos with at most this many comments." }, { "name": "minShares", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Only return videos with at least this many shares." }, "required": false, "description": "Only return videos with at least this many shares." }, { "name": "maxShares", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Only return videos with at most this many shares." }, "required": false, "description": "Only return videos with at most this many shares." }, { "name": "minSaves", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Only return videos with at least this many saves." }, "required": false, "description": "Only return videos with at least this many saves." }, { "name": "maxSaves", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Only return videos with at most this many saves." }, "required": false, "description": "Only return videos with at most this many saves." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "created_at": { "type": [ "string", "null" ], "description": "Date the video was posted, formatted `YYYY-MM-DD HH:mm:ss`." }, "modified_at": { "type": [ "string", "null" ], "description": "Date the video's counters were last refreshed, formatted `YYYY-MM-DD`." }, "username": { "type": [ "string", "null" ], "description": "TikTok username of the video poster." }, "video_id": { "type": [ "string", "null" ], "description": "TikTok video ID." }, "thumbnail_url": { "type": [ "string", "null" ], "description": "URL of the video thumbnail." }, "avatar_url": { "type": [ "string", "null" ], "description": "URL of the poster's profile image. Null when no avatar has been cached." }, "followers": { "type": [ "integer", "null" ], "minimum": 0, "description": "Follower count of the poster at observation time." }, "cm_id": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "nullable": true, "description": "Chartmetric artist ID of the poster when linked. Null if no link is known." }, "link": { "type": [ "string", "null" ], "description": "Direct URL to the TikTok video." }, "description": { "type": [ "string", "null" ], "description": "The video's caption, including hashtags and mentions." }, "influencerCountries": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "ISO 3166-1 alpha-2 country codes inferred for the poster. Empty when no country is known." }, "sound_id": { "type": [ "string", "null" ], "description": "TikTok's ID for the sound used in the video." }, "tiktok": { "type": [ "integer", "null" ], "description": "Chartmetric's internal ID for that sound." }, "cm_track": { "type": [ "integer", "null" ], "description": "Chartmetric track ID the sound resolves to." }, "tiktok_video": { "type": [ "integer", "null" ], "description": "Chartmetric's internal ID for the video." }, "stats": { "type": [ "object", "null" ], "properties": { "likes": { "type": [ "integer", "null" ], "minimum": 0, "description": "Cumulative like count for the video." }, "comments": { "type": [ "integer", "null" ], "minimum": 0, "description": "Cumulative comment count for the video." }, "views": { "type": [ "integer", "null" ], "minimum": 0, "description": "Cumulative view count for the video." }, "shares": { "type": [ "integer", "null" ], "minimum": 0, "description": "Cumulative share count for the video." }, "saves": { "type": [ "integer", "null" ], "minimum": 0, "description": "Cumulative save count for the video." } }, "description": "Engagement stats for the video, as of `modified_at`." }, "tiktokVideoHistoricalStats": { "type": "array", "items": { "type": "object", "properties": { "views": { "type": [ "integer", "null" ], "description": "Views recorded on that date." }, "likes": { "type": [ "integer", "null" ], "description": "Likes recorded on that date." }, "shares": { "type": [ "integer", "null" ], "description": "Shares recorded on that date." }, "saves": { "type": [ "integer", "null" ], "description": "Saves recorded on that date." }, "comments": { "type": [ "integer", "null" ], "description": "Comments recorded on that date." }, "timestp": { "type": [ "string", "null" ], "description": "Date of the snapshot, formatted `YYYY-MM-DD`." } } }, "description": "Daily snapshots of the counters above, oldest first, covering the history held for the video." }, "likesPercentChange": { "type": [ "number", "null" ], "format": "float", "description": "Percent change in likes across the comparison window. Null when the video has too little history to compare." }, "commentsPercentChange": { "type": [ "number", "null" ], "format": "float", "description": "Percent change in comments across the same window." }, "viewsPercentChange": { "type": [ "number", "null" ], "format": "float", "description": "Percent change in views across the same window." }, "sharesPercentChange": { "type": [ "number", "null" ], "format": "float", "description": "Percent change in shares across the same window." }, "savesPercentChange": { "type": [ "number", "null" ], "format": "float", "description": "Percent change in saves across the same window." }, "likesValueChange": { "type": [ "integer", "null" ], "description": "Absolute change in likes across the same window." }, "commentsValueChange": { "type": [ "integer", "null" ], "description": "Absolute change in comments across the same window." }, "viewsValueChange": { "type": [ "integer", "null" ], "description": "Absolute change in views across the same window." }, "sharesValueChange": { "type": [ "integer", "null" ], "description": "Absolute change in shares across the same window." }, "savesValueChange": { "type": [ "integer", "null" ], "description": "Absolute change in saves across the same window." }, "track_name": { "type": [ "string", "null" ], "description": "Name of the artist's track the video used. Null when the sound resolves to no track." } } } }, { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "created_at": { "type": [ "string", "null" ], "description": "Date the video was posted, formatted `YYYY-MM-DD HH:mm:ss`." }, "modified_at": { "type": [ "string", "null" ], "description": "Date the video's counters were last refreshed, formatted `YYYY-MM-DD`." }, "username": { "type": [ "string", "null" ], "description": "TikTok username of the video poster." }, "video_id": { "type": [ "string", "null" ], "description": "TikTok video ID." }, "thumbnail_url": { "type": [ "string", "null" ], "description": "URL of the video thumbnail." }, "avatar_url": { "type": [ "string", "null" ], "description": "URL of the poster's profile image. Null when no avatar has been cached." }, "followers": { "type": [ "integer", "null" ], "minimum": 0, "description": "Follower count of the poster at observation time." }, "cm_id": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "nullable": true, "description": "Chartmetric artist ID of the poster when linked. Null if no link is known." }, "link": { "type": [ "string", "null" ], "description": "Direct URL to the TikTok video." }, "description": { "type": [ "string", "null" ], "description": "The video's caption, including hashtags and mentions." }, "influencerCountries": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "ISO 3166-1 alpha-2 country codes inferred for the poster. Empty when no country is known." }, "sound_id": { "type": [ "string", "null" ], "description": "TikTok's ID for the sound used in the video." }, "tiktok": { "type": [ "integer", "null" ], "description": "Chartmetric's internal ID for that sound." }, "cm_track": { "type": [ "integer", "null" ], "description": "Chartmetric track ID the sound resolves to." }, "tiktok_video": { "type": [ "integer", "null" ], "description": "Chartmetric's internal ID for the video." }, "stats": { "type": [ "object", "null" ], "properties": { "likes": { "type": [ "integer", "null" ], "minimum": 0, "description": "Cumulative like count for the video." }, "comments": { "type": [ "integer", "null" ], "minimum": 0, "description": "Cumulative comment count for the video." }, "views": { "type": [ "integer", "null" ], "minimum": 0, "description": "Cumulative view count for the video." }, "shares": { "type": [ "integer", "null" ], "minimum": 0, "description": "Cumulative share count for the video." }, "saves": { "type": [ "integer", "null" ], "minimum": 0, "description": "Cumulative save count for the video." } }, "description": "Engagement stats for the video, as of `modified_at`." }, "tiktokVideoHistoricalStats": { "type": "array", "items": { "type": "object", "properties": { "views": { "type": [ "integer", "null" ], "description": "Views recorded on that date." }, "likes": { "type": [ "integer", "null" ], "description": "Likes recorded on that date." }, "shares": { "type": [ "integer", "null" ], "description": "Shares recorded on that date." }, "saves": { "type": [ "integer", "null" ], "description": "Saves recorded on that date." }, "comments": { "type": [ "integer", "null" ], "description": "Comments recorded on that date." }, "timestp": { "type": [ "string", "null" ], "description": "Date of the snapshot, formatted `YYYY-MM-DD`." } } }, "description": "Daily snapshots of the counters above, oldest first, covering the history held for the video." }, "likesPercentChange": { "type": [ "number", "null" ], "format": "float", "description": "Percent change in likes across the comparison window. Null when the video has too little history to compare." }, "commentsPercentChange": { "type": [ "number", "null" ], "format": "float", "description": "Percent change in comments across the same window." }, "viewsPercentChange": { "type": [ "number", "null" ], "format": "float", "description": "Percent change in views across the same window." }, "sharesPercentChange": { "type": [ "number", "null" ], "format": "float", "description": "Percent change in shares across the same window." }, "savesPercentChange": { "type": [ "number", "null" ], "format": "float", "description": "Percent change in saves across the same window." }, "likesValueChange": { "type": [ "integer", "null" ], "description": "Absolute change in likes across the same window." }, "commentsValueChange": { "type": [ "integer", "null" ], "description": "Absolute change in comments across the same window." }, "viewsValueChange": { "type": [ "integer", "null" ], "description": "Absolute change in views across the same window." }, "sharesValueChange": { "type": [ "integer", "null" ], "description": "Absolute change in shares across the same window." }, "savesValueChange": { "type": [ "integer", "null" ], "description": "Absolute change in saves across the same window." }, "track_name": { "type": [ "string", "null" ], "description": "Name of the artist's track the video used. Null when the sound resolves to no track." } } }, "description": "The videos on this page." }, "total": { "type": [ "integer", "null" ], "minimum": 0, "description": "Videos matching the current filters across all pages." }, "available_count": { "type": [ "integer", "null" ], "minimum": 0, "description": "Same value as `total`. The handler populates both from one filtered count; kept for callers already reading it." }, "lasted_updated_at": { "type": [ "string", "null" ], "description": "Date the track's videos were last refreshed. The field name carries a long-standing typo." } } } ], "description": "A bare array by default; the envelope above when `withTotal=true`." } }, "additionalProperties": false }, "examples": { "default": { "value": { "obj": [ { "created_at": "2026-05-11 00:00:00", "modified_at": "2026-08-19", "username": "haileybieber", "followers": 19338972, "video_id": "7638754937748360478", "cm_id": 11647783, "sound_id": "x-7559312683885201425", "tiktok": 25646255, "cm_track": 154524166, "track_name": "Choosin' Texas", "tiktok_video": 845854366, "influencerCountries": [ "US" ], "avatar_url": "https://d2xuw6r9djpzwq.cloudfront.net/tiktok/users/6772347709954851846.jpg", "link": "https://www.tiktok.com/@haileybieber/video/7638754937748360478", "stats": { "likes": 3056560, "comments": 13728, "views": 27629256, "shares": 74701, "saves": 138553 }, "description": "Choosin' Texas", "thumbnail_url": "https://d2xuw6r9djpzwq.cloudfront.net/tiktok/videos/7638754937748360478.jpg", "tiktokVideoHistoricalStats": [ { "views": 25600000, "likes": 2900000, "shares": 73100, "saves": 133600, "comments": 13300, "timestp": "2026-07-08" }, { "views": 25700000, "likes": 2900000, "shares": 73200, "saves": 133900, "comments": 13300, "timestp": "2026-07-09" } ], "likesPercentChange": null, "commentsPercentChange": null, "viewsPercentChange": null, "sharesPercentChange": null, "savesPercentChange": null, "likesValueChange": null, "commentsValueChange": null, "viewsValueChange": null, "sharesValueChange": null, "savesValueChange": null } ] } } } } } } } } }, "/api/artist/{id}/tiktok-top-influencers": { "get": { "summary": "💎 Premium — List Top TikTok Influencers for an Artist", "tags": [ "Artist" ], "operationId": "listArtistTikTokTopInfluencers", "description": "The TikTok creators who used any of the artist's sounds, one row each -- the table the app shows on its TikTok Sounds page. Where the breakdown endpoint reports how the group splits by country or language, this reports who the creators are. Paged and filterable on every column the app's own filters use; `total` counts what matches the current filters rather than the whole set.", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer", "minimum": 2, "maximum": 2147483647, "not": { "enum": [ 1 ] }, "description": "Chartmetric artist ID. Note: id=1 ('Various Artists') is rejected." }, "required": true, "description": "Chartmetric artist ID. Note: id=1 ('Various Artists') is rejected.", "examples": { "default": { "value": 2 } } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Influencers per page. Defaults to 25, max 100.", "default": 25 }, "required": false, "description": "Influencers per page. Defaults to 25, max 100." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Influencers to skip, for paging past the first `limit` rows. Defaults to 0, max 10,000." }, "required": false, "description": "Influencers to skip, for paging past the first `limit` rows. Defaults to 0, max 10,000." }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "enum": [ "rank", "totalFollowers", "totalViews", "totalLikes", "totalComments", "engagementRate", "totalSaves", "totalShares", "dateAdded", "avgViews", "avgLikes", "avgComments", "avgSaves", "avgShares", "avgEngagementRate", "videoCount", "lastDatePosted" ], "description": "Column to sort by. Defaults to `rank`, the order the app lists them in.", "default": "rank" }, "required": false, "description": "Column to sort by. Defaults to `rank`, the order the app lists them in." }, { "name": "sortDirection", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort direction. Defaults to `asc`.", "default": "asc" }, "required": false, "description": "Sort direction. Defaults to `asc`." }, { "name": "isVerified", "in": "query", "schema": { "type": "boolean", "description": "Restrict to verified accounts when true, unverified when false. Omit for both." }, "required": false, "description": "Restrict to verified accounts when true, unverified when false. Omit for both." }, { "name": "country[]", "in": "query", "schema": { "type": "array", "items": { "type": "string" }, "description": "ISO 3166-1 alpha-2 country codes to include. Repeat the param or pass a comma-free list." }, "required": false, "description": "ISO 3166-1 alpha-2 country codes to include. Repeat the param or pass a comma-free list." }, { "name": "categories[]", "in": "query", "schema": { "type": "array", "items": { "type": "string" }, "description": "Broad content categories to include. Repeat the param or pass a comma-free list." }, "required": false, "description": "Broad content categories to include. Repeat the param or pass a comma-free list." }, { "name": "ageGroup[]", "in": "query", "schema": { "type": "array", "items": { "type": "string" }, "description": "Age brackets, e.g. `18-24` to include. Repeat the param or pass a comma-free list." }, "required": false, "description": "Age brackets, e.g. `18-24` to include. Repeat the param or pass a comma-free list." }, { "name": "gender[]", "in": "query", "schema": { "type": "array", "items": { "type": "string" }, "description": "Genders to include. Repeat the param or pass a comma-free list." }, "required": false, "description": "Genders to include. Repeat the param or pass a comma-free list." }, { "name": "ethnicity[]", "in": "query", "schema": { "type": "array", "items": { "type": "string" }, "description": "Ethnicities to include. Repeat the param or pass a comma-free list." }, "required": false, "description": "Ethnicities to include. Repeat the param or pass a comma-free list." }, { "name": "language[]", "in": "query", "schema": { "type": "array", "items": { "type": "string" }, "description": "Primary languages to include. Repeat the param or pass a comma-free list." }, "required": false, "description": "Primary languages to include. Repeat the param or pass a comma-free list." }, { "name": "type[]", "in": "query", "schema": { "type": "array", "items": { "type": "string" }, "description": "Creator types, e.g. `Brand` to include. Repeat the param or pass a comma-free list." }, "required": false, "description": "Creator types, e.g. `Brand` to include. Repeat the param or pass a comma-free list." }, { "name": "minFollowers", "in": "query", "schema": { "type": "number", "format": "float", "description": "Only influencers with at least this followers." }, "required": false, "description": "Only influencers with at least this followers." }, { "name": "maxFollowers", "in": "query", "schema": { "type": "number", "format": "float", "description": "Only influencers with at most this followers." }, "required": false, "description": "Only influencers with at most this followers." }, { "name": "minAvgViews", "in": "query", "schema": { "type": "number", "format": "float", "description": "Only influencers with at least this average views." }, "required": false, "description": "Only influencers with at least this average views." }, { "name": "maxAvgViews", "in": "query", "schema": { "type": "number", "format": "float", "description": "Only influencers with at most this average views." }, "required": false, "description": "Only influencers with at most this average views." }, { "name": "minAvgLikes", "in": "query", "schema": { "type": "number", "format": "float", "description": "Only influencers with at least this average likes." }, "required": false, "description": "Only influencers with at least this average likes." }, { "name": "maxAvgLikes", "in": "query", "schema": { "type": "number", "format": "float", "description": "Only influencers with at most this average likes." }, "required": false, "description": "Only influencers with at most this average likes." }, { "name": "minAvgComments", "in": "query", "schema": { "type": "number", "format": "float", "description": "Only influencers with at least this average comments." }, "required": false, "description": "Only influencers with at least this average comments." }, { "name": "maxAvgComments", "in": "query", "schema": { "type": "number", "format": "float", "description": "Only influencers with at most this average comments." }, "required": false, "description": "Only influencers with at most this average comments." }, { "name": "minAvgSaves", "in": "query", "schema": { "type": "number", "format": "float", "description": "Only influencers with at least this average saves." }, "required": false, "description": "Only influencers with at least this average saves." }, { "name": "maxAvgSaves", "in": "query", "schema": { "type": "number", "format": "float", "description": "Only influencers with at most this average saves." }, "required": false, "description": "Only influencers with at most this average saves." }, { "name": "minAvgShares", "in": "query", "schema": { "type": "number", "format": "float", "description": "Only influencers with at least this average shares." }, "required": false, "description": "Only influencers with at least this average shares." }, { "name": "maxAvgShares", "in": "query", "schema": { "type": "number", "format": "float", "description": "Only influencers with at most this average shares." }, "required": false, "description": "Only influencers with at most this average shares." }, { "name": "minAvgEngagementRate", "in": "query", "schema": { "type": "number", "format": "float", "description": "Only influencers with at least this average engagement rate." }, "required": false, "description": "Only influencers with at least this average engagement rate." }, { "name": "maxAvgEngagementRate", "in": "query", "schema": { "type": "number", "format": "float", "description": "Only influencers with at most this average engagement rate." }, "required": false, "description": "Only influencers with at most this average engagement rate." }, { "name": "minVideoCount", "in": "query", "schema": { "type": "number", "format": "float", "description": "Only influencers with at least this video count." }, "required": false, "description": "Only influencers with at least this video count." }, { "name": "maxVideoCount", "in": "query", "schema": { "type": "number", "format": "float", "description": "Only influencers with at most this video count." }, "required": false, "description": "Only influencers with at most this video count." }, { "name": "lastDatePostedFrom", "in": "query", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Only influencers who last posted on or after this date (`YYYY-MM-DD`)." }, "required": false, "description": "Only influencers who last posted on or after this date (`YYYY-MM-DD`)." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "full_name": { "type": [ "string", "null" ], "description": "The creator's display name." }, "handle": { "type": [ "string", "null" ], "description": "TikTok handle, including the leading `@`." }, "is_verified": { "type": "boolean", "description": "Whether TikTok verifies the account." }, "country": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-2 code for the creator's own country." }, "contacts": { "type": "array", "items": { "type": "string" }, "description": "Public contact links the creator lists." }, "type": { "type": [ "string", "null" ], "description": "Creator classification, e.g. `Brand`, `Celebrity`, `Social Media Creator`." }, "language": { "type": [ "string", "null" ], "description": "The creator's primary language, lower-case." }, "ethnicity": { "type": "array", "items": { "type": "string" }, "description": "Ethnicities attributed to the creator, lower-case." }, "age_group": { "type": [ "string", "null" ], "description": "Age bracket, e.g. `18-24`." }, "gender": { "type": [ "string", "null" ], "description": "Gender, lower-case." }, "categories": { "type": "array", "items": { "type": "string" }, "description": "Broad content categories." }, "sub_categories": { "type": "array", "items": { "type": "string" }, "description": "Granular creator tags underneath those categories." }, "top_hashtags": { "type": "array", "items": { "type": "string" }, "description": "Hashtags the creator uses most." }, "genres": { "type": "array", "items": { "type": "string" }, "description": "Music genres attributed to the creator." }, "bio": { "type": [ "string", "null" ], "description": "The creator's TikTok bio." }, "featured_track": { "type": [ "string", "null" ], "description": "Name of the track their video used." }, "followers": { "type": [ "integer", "null" ], "description": "TikTok follower count." }, "engagement_rate": { "type": [ "number", "null" ], "format": "float", "description": "Engagement rate averaged across the creator's recent videos." }, "avg_views": { "type": [ "integer", "null" ], "description": "Views averaged across those videos." }, "avg_likes": { "type": [ "integer", "null" ], "description": "Likes averaged across those videos." }, "avg_comments": { "type": [ "integer", "null" ], "description": "Comments averaged across those videos." }, "avg_saves": { "type": [ "integer", "null" ], "description": "Saves averaged across those videos." }, "avg_shares": { "type": [ "integer", "null" ], "description": "Shares averaged across those videos." }, "video_count": { "type": [ "integer", "null" ], "description": "Videos on the account." }, "top_videos": { "type": "array", "items": { "type": "object", "properties": { "video_id": { "type": [ "string", "null" ], "description": "TikTok's ID for the video." }, "video_url": { "type": [ "string", "null" ], "description": "Direct link to the video." }, "thumbnail_url": { "type": [ "string", "null" ], "description": "Thumbnail URL." }, "views": { "type": [ "integer", "null" ], "description": "Views on the video." }, "likes": { "type": [ "integer", "null" ], "description": "Likes on the video." }, "comments": { "type": [ "integer", "null" ], "description": "Comments on the video." }, "saves": { "type": [ "integer", "null" ], "description": "Saves on the video." }, "shares": { "type": [ "integer", "null" ], "description": "Shares on the video." }, "engagement_rate": { "type": [ "number", "null" ], "format": "float", "description": "Engagement rate for the video." }, "created_at": { "type": [ "string", "null" ], "description": "Date the video was posted." }, "description": { "type": [ "string", "null" ], "description": "The video's caption." }, "track_name": { "type": [ "string", "null" ], "description": "Track the video's sound belongs to." } } }, "description": "Up to five of the creator's videos using the queried sounds." } } }, "description": "Influencers on this page." }, "total": { "type": "integer", "minimum": 0, "description": "Influencers matching the current filters, across all pages." } }, "required": [ "data", "total" ] } }, "additionalProperties": false }, "examples": { "default": { "value": { "obj": { "total": 384, "data": [ { "full_name": "Hailey Bieber", "handle": "@haileybieber", "is_verified": true, "country": "US", "contacts": [], "type": "Celebrity", "language": "english", "ethnicity": [ "white" ], "age_group": "25-34", "gender": "female", "categories": [ "Beauty & Cosmetics" ], "sub_categories": [ "makeup", "skincare" ], "top_hashtags": [ "rhodeskin", "grwm" ], "genres": [ "pop" ], "bio": "founder of rhode", "featured_track": "Choosin' Texas", "followers": 19338972, "engagement_rate": 0.0077, "avg_views": 418531, "avg_likes": 42600, "avg_comments": 253, "avg_saves": 2024, "avg_shares": 1875, "video_count": 8233, "top_videos": [ { "video_id": "7638754937748360478", "video_url": "https://www.tiktok.com/@haileybieber/video/7638754937748360478", "thumbnail_url": "https://d2xuw6r9djpzwq.cloudfront.net/tiktok/videos/7638754937748360478.jpg", "views": 27629256, "likes": 3056560, "comments": 13728, "saves": 138553, "shares": 74701, "engagement_rate": 0.1161, "created_at": "2026-05-11", "description": "Choosin' Texas", "track_name": "Choosin' Texas" } ] } ] } } } } } } } } } }, "/api/artist/{id}/tiktok-influencer-stats": { "get": { "summary": "💎 Premium — Get Influencer Breakdown for an Artist", "tags": [ "Artist" ], "operationId": "getArtistTikTokInfluencerStats", "description": "Distribution of the TikTok creators who used the artist's sounds, one axis per call. `dimension` selects the axis: `country`, `category` (broad content categories), `subcategory` (the granular creator tags beneath them), `age-gender`, or `language`. Aggregates only — the endpoint reports how many creators fall in each bucket, not who they are. A creator holds exactly one country, age/gender bucket and language, so those shares sum to 1 and `total` is the creator count; a creator can hold several categories, so `category` and `subcategory` return counts with `share` and `total` null and `multi_label` true. Distinct from `tiktok-audience-stats`, which describes the artist's own TikTok followers rather than the creators using their sounds.", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer", "minimum": 2, "maximum": 2147483647, "not": { "enum": [ 1 ] }, "description": "Chartmetric artist ID. Note: id=1 ('Various Artists') is rejected." }, "required": true, "description": "Chartmetric artist ID. Note: id=1 ('Various Artists') is rejected.", "examples": { "default": { "value": 2 } } }, { "name": "dimension", "in": "query", "schema": { "type": "string", "enum": [ "country", "category", "subcategory", "age-gender", "language" ], "description": "Which breakdown to return. `category` is the broad creator-content layer, `subcategory` the granular one; a creator can hold several of either, so those two report counts without a share.", "default": "country" }, "required": false, "description": "Which breakdown to return. `category` is the broad creator-content layer, `subcategory` the granular one; a creator can hold several of either, so those two report counts without a share." }, { "name": "periodDays", "in": "query", "schema": { "type": "number", "format": "float", "enum": [ 0, 7, 30, 90 ], "description": "Rolling window, in days, over the date creators last posted with the artist's sounds. `0` covers all time." }, "required": false, "description": "Rolling window, in days, over the date creators last posted with the artist's sounds. `0` covers all time." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "object", "properties": { "dimension": { "type": "string", "enum": [ "country", "category", "subcategory", "age-gender", "language" ], "description": "The requested dimension, echoed back." }, "period_days": { "type": "number", "format": "float", "enum": [ 0, 7, 30, 90 ], "description": "The requested rolling window in days, echoed back. `0` covers all time." }, "total": { "type": [ "integer", "null" ], "minimum": 0, "description": "Creators the distribution covers. Null on the multi-label dimensions, where counts cannot be summed into a creator total." }, "multi_label": { "type": "boolean", "description": "True when a creator can appear in more than one bucket — `category` and `subcategory`. Those dimensions report counts without a share." }, "available_period_days": { "type": [ "array", "null" ], "items": { "type": "number", "format": "float" }, "description": "Windows this data is held for. Populated for `age-gender` and `language`; null elsewhere." }, "data": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "description": "Bucket label — an ISO 3166-1 alpha-2 code for `country`, `age|gender` for `age-gender`, otherwise the category, tag or language name." }, "count": { "type": "integer", "minimum": 0, "description": "Creators in this bucket." }, "share": { "type": [ "number", "null" ], "format": "float", "description": "Bucket's fraction of `total`, 0–1. Null on the multi-label dimensions." }, "delta": { "type": [ "integer", "null" ], "description": "Change in `count` against the preceding window of the same length. Null where the dimension carries no comparison." }, "age_group": { "type": [ "string", "null" ], "description": "Age bracket half of `value`. Present on `age-gender` only; null when the classifier resolved a gender but no age." }, "gender": { "type": [ "string", "null" ], "description": "Gender half of `value`. Present on `age-gender` only; null when the classifier resolved an age but no gender." } }, "required": [ "value", "count" ] }, "description": "Buckets, largest first." } }, "required": [ "dimension", "period_days", "multi_label", "data" ] } }, "additionalProperties": false }, "examples": { "default": { "value": { "obj": { "dimension": "age-gender", "period_days": 30, "total": 91, "multi_label": false, "available_period_days": [ 0, 7, 30, 90 ], "data": [ { "value": "25-34|female", "age_group": "25-34", "gender": "female", "count": 31, "share": 0.340659, "delta": 6 }, { "value": "18-24|female", "age_group": "18-24", "gender": "female", "count": 30, "share": 0.32967, "delta": -6 } ] } } } } } } } } } }, "/api/artist/{id}/tiktok-audience-stats": { "get": { "summary": "💎 Premium — TikTok Audience Stats", "tags": [ "Artist" ], "operationId": "getArtistTiktokAudienceStats", "description": "TikTok audience analysis for an artist (latest report or historical via `date`). Top follower countries, gender/age + gender rollups, and notable followers plus engagement counters (`followers`, `avg_likes_per_post`, `avg_comments_per_post`, `engagement_rate`). Rate fields come from uncast PG numerics so may surface as strings. The response also carries the misspelled `avg_commments_per_post` with the same value; it is removed after October 1st, 2026. The vendor panel behind `notable_followers` was retired — the key stays in the response but stops updating from October 1st, 2026, carrying the last values collected from the panel or an empty array where none were.", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer", "minimum": 2, "maximum": 2147483647, "not": { "enum": [ 1 ] }, "description": "Chartmetric artist ID. Note: id=1 ('Various Artists') is rejected." }, "required": true, "description": "Chartmetric artist ID. Note: id=1 ('Various Artists') is rejected.", "examples": { "default": { "value": 2 } } }, { "name": "date", "in": "query", "schema": { "type": "string", "format": "date", "description": "Historical date (`YYYY-MM-DD`). When omitted, returns the most recent available report. Use the dates endpoint to discover available dates." }, "required": false, "description": "Historical date (`YYYY-MM-DD`). When omitted, returns the most recent available report. Use the dates endpoint to discover available dates." }, { "name": "geoOnly", "in": "query", "schema": { "type": "boolean", "description": "If true, drop demographic / brand-affinity / interest / notable-followers blocks and return only geo + engagement counters.", "default": false }, "required": false, "description": "If true, drop demographic / brand-affinity / interest / notable-followers blocks and return only geo + engagement counters." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "object", "properties": { "top_countries": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "description": "Country name." }, "code": { "type": [ "string", "null" ], "description": "Lower-cased country code (ISO 3166-1 alpha-2)." }, "percent": { "type": [ "string", "null" ], "description": "Audience share for the country, as a percent string with 2 decimals." }, "followers": { "type": [ "integer", "null" ], "description": "Number of audience followers in this country." }, "subscribers": { "type": [ "integer", "null" ], "description": "Number of audience subscribers in this country (YouTube)." }, "likes": { "type": [ "integer", "null" ], "description": "Number of audience likes attributable to this country." }, "comments": { "type": [ "integer", "null" ], "description": "Number of audience comments from this country (YouTube commenters)." } } }, "description": "Top countries among the artist's TikTok followers." }, "audience_genders_per_age": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": [ "string", "null" ], "description": "Age bucket code (e.g. `13-17`, `18-24`, `25-34`)." }, "male": { "type": [ "string", "null" ], "description": "Male share for the age bucket, as a percent string." }, "female": { "type": [ "string", "null" ], "description": "Female share for the age bucket, as a percent string." } } }, "description": "Follower gender share per age bucket." }, "audience_genders": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": [ "string", "null" ], "description": "Gender code (`male` or `female`); may surface uppercase for some YouTube rollups." }, "weight": { "type": [ "string", "null" ], "description": "Audience share for the gender, as a percent string." } } }, "description": "Follower gender rollup." }, "notable_followers": { "type": "array", "items": { "type": "object", "properties": { "user_id": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Platform-native user ID of the notable follower." }, "username": { "type": [ "string", "null" ], "description": "Username on the platform." }, "custom_name": { "type": [ "string", "null" ], "description": "YouTube custom channel name." }, "handle": { "type": [ "string", "null" ], "description": "YouTube channel handle." }, "picture": { "type": [ "string", "null" ], "description": "Profile picture URL." }, "fullname": { "type": [ "string", "null" ], "description": "Display / full name." }, "url": { "type": [ "string", "null" ], "description": "Profile URL." }, "followers": { "type": [ "integer", "null" ], "description": "Follower count of the notable user (Instagram, TikTok)." }, "subscribers": { "type": [ "integer", "null" ], "description": "Subscriber count of the notable user (YouTube)." }, "is_verified": { "anyOf": [ { "type": "boolean" }, { "type": "string" } ], "nullable": true, "description": "True when the user is platform-verified." }, "engagements": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "User's engagement metric on the platform." }, "avg_likes": { "type": [ "integer", "null" ], "description": "Average likes per post (YouTube)." }, "avg_views": { "type": [ "integer", "null" ], "description": "Average views per video (YouTube)." }, "geo": { "type": [ "object", "null" ], "properties": { "country": { "type": [ "object", "null" ], "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Identifier of the geo level (country / state / city)." }, "name": { "type": [ "string", "null" ], "description": "Display name of the geo level." }, "code": { "type": [ "string", "null" ], "description": "Code of the geo level (e.g. ISO country code)." }, "coords": { "type": [ "object", "null" ], "properties": { "lat": { "type": [ "number", "null" ], "format": "float", "description": "Latitude." }, "lon": { "type": [ "number", "null" ], "format": "float", "description": "Longitude." } }, "description": "Geographic coordinates of the geo level." } }, "description": "Geo level (country / state / city) with id, name, code, and coordinates." }, "state": { "type": [ "object", "null" ], "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Identifier of the geo level (country / state / city)." }, "name": { "type": [ "string", "null" ], "description": "Display name of the geo level." }, "code": { "type": [ "string", "null" ], "description": "Code of the geo level (e.g. ISO country code)." }, "coords": { "type": [ "object", "null" ], "properties": { "lat": { "type": [ "number", "null" ], "format": "float", "description": "Latitude." }, "lon": { "type": [ "number", "null" ], "format": "float", "description": "Longitude." } }, "description": "Geographic coordinates of the geo level." } }, "description": "Geo level (country / state / city) with id, name, code, and coordinates." }, "city": { "type": [ "object", "null" ], "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Identifier of the geo level (country / state / city)." }, "name": { "type": [ "string", "null" ], "description": "Display name of the geo level." }, "code": { "type": [ "string", "null" ], "description": "Code of the geo level (e.g. ISO country code)." }, "coords": { "type": [ "object", "null" ], "properties": { "lat": { "type": [ "number", "null" ], "format": "float", "description": "Latitude." }, "lon": { "type": [ "number", "null" ], "format": "float", "description": "Longitude." } }, "description": "Geographic coordinates of the geo level." } }, "description": "Geo level (country / state / city) with id, name, code, and coordinates." } }, "description": "Geo location of the user. Each level (`country`, `state`, `city`) carries `{id, name, code, coords:{lat,lon}}`; absent levels are `null` or `{}`. Population varies by platform." } } }, "description": "Notable followers of the TikTok account. Deprecated effective October 1st, 2026 — no longer updated. The key stays in the response, carrying either the last values collected from the retired panel or an empty array for accounts that never had them.", "deprecated": true }, "followers": { "type": [ "integer", "null" ], "description": "Total TikTok follower count for the artist." }, "avg_likes_per_post": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Average likes per post. May arrive as string (uncast PG numeric)." }, "avg_commments_per_post": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Average comments per post. May arrive as string. Deprecated — this misspelling is removed after October 1st, 2026; use `avg_comments_per_post`.", "deprecated": true }, "avg_comments_per_post": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Average comments per post. May arrive as string." }, "engagement_rate": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Engagement rate as a 0–1 ratio. May arrive as string." }, "timestp": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Date of the retrieved data (ISO 8601)." } } } }, "additionalProperties": false }, "examples": { "default": { "value": { "obj": { "top_countries": [ { "name": "United States", "code": "us", "percent": "20.10", "followers": 1500000 } ], "audience_genders": [ { "code": "male", "weight": "60.00" }, { "code": "female", "weight": "40.00" } ], "followers": 7500000, "avg_likes_per_post": "125000", "avg_commments_per_post": "3400", "avg_comments_per_post": "3400", "engagement_rate": "0.0217", "timestp": "2022-04-03" } } } } } } } } } }, "/api/artist/{id}/top-tracks/{source}": { "get": { "summary": "Artist Top Tracks by Source", "tags": [ "Artist" ], "operationId": "listArtistTopTracks", "description": "Top tracks for an artist on a given source. `source` is one of `cm` (Chartmetric's overall ranking), `youtubeforartist` (YouTube for Artists), or `tiktok`. Row shape varies per source — all branches emit per-track identifiers (`cm_track`, `isrc`, sound id) and engagement counters; `tiktok` additionally returns a `trend` time-series + `engagementRate`. Counter fields may surface as string (uncast PG / Snowflake aggregates).", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer", "minimum": 2, "maximum": 2147483647, "not": { "enum": [ 1 ] }, "description": "Chartmetric artist ID. Note: id=1 ('Various Artists') is rejected." }, "required": true, "description": "Chartmetric artist ID. Note: id=1 ('Various Artists') is rejected.", "examples": { "default": { "value": 2 } } }, { "name": "source", "in": "path", "schema": { "type": "string", "enum": [ "cm", "youtubeforartist", "tiktok" ], "description": "Short-form / social platform. One of `cm`, `youtubeforartist`, `tiktok`. Row shape varies by source." }, "required": true, "description": "Short-form / social platform. One of `cm`, `youtubeforartist`, `tiktok`. Row shape varies by source.", "examples": { "default": { "value": "cm" } } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "maximum": 100, "description": "Maximum number of tracks to return. Defaults to 10, max 100.", "default": 10 }, "required": false, "description": "Maximum number of tracks to return. Defaults to 10, max 100." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "array", "items": { "type": "object", "properties": { "cm_track": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 2147483647 }, { "type": "object", "properties": {} } ], "nullable": true, "description": "Chartmetric track ID, or a track-summary object for instagram/instagram_reels rows." }, "name": { "type": [ "string", "null" ], "description": "Track name (TikTok rows)." }, "track_name": { "type": [ "string", "null" ], "description": "Track name (YouTube Shorts rows)." }, "image_url": { "type": [ "string", "null" ], "description": "Track image URL (TikTok rows)." }, "track_image_url": { "type": [ "string", "null" ], "description": "Track image URL (YouTube Shorts rows)." }, "audio_url": { "type": [ "string", "null" ], "description": "Track preview audio URL." }, "isrc": { "type": [ "string", "null" ], "description": "International Standard Recording Code." }, "tiktok": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "TikTok sound ID." }, "tiktok_id": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "TikTok's own ID for the sound." }, "tiktok_track_id": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "TikTok track ID." }, "tiktok_url": { "type": [ "string", "null" ], "description": "TikTok URL for the sound." }, "sound_id": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "YouTube Shorts sound ID." }, "tags": { "type": [ "string", "null" ], "description": "Comma-separated track genres." }, "views": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "View count." }, "likes": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Like count." }, "comments": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Comment count." }, "posts": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Post count using the track/sound." }, "views_percentage": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Percentage of platform views attributable to the artist's tracks." }, "upload_date": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Track upload date (ISO 8601)." }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Track creation date (ISO 8601)." }, "monthly_diff_percent": { "type": [ "number", "null" ], "format": "float", "description": "Monthly percentage change in `posts`." }, "score": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric track score." }, "trend": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "timestp": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Date of the trend data point (ISO 8601)." }, "value": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Post count at this date." } } }, "description": "Historical post-count trend in ascending date order." }, "engagementRate": { "type": [ "number", "null" ], "format": "float", "description": "Track engagement rate (0–1)." } } } } }, "required": [ "obj" ], "additionalProperties": false }, "examples": { "default": { "value": { "obj": [ { "tiktok": "7091431347681856000", "tiktok_id": "7091431347681856000", "tiktok_track_id": "7091431347681856000", "tiktok_url": "https://www.tiktok.com/music/original-sound-7091431347681856000", "isrc": "USUM72112345", "cm_track": 66234422, "name": "original sound", "image_url": "https://p16-sign.tiktokcdn-us.com/...", "audio_url": "https://v16-webapp.tiktok.com/...", "tags": "pop,dance pop", "views": 12400000, "likes": 850000, "comments": 4200, "posts": 18450, "monthly_diff_percent": 0.1234, "created_at": "2022-04-21T12:00:00.000Z", "score": 82, "trend": [ { "timestp": "2022-04-01", "value": 12000 } ], "engagementRate": 0.0689 } ] } } } } } } } } }, "/api/artist/{id}/artist-rank": { "get": { "summary": "Artist Rank (Latest)", "tags": [ "Artist" ], "operationId": "getArtistRank", "description": "Artist's current rank within the Chartmetric artist universe for a given `metric` (default `cm_artist_rank`). Pass `code2` to slice by country, `genre` to slice by genre. For the default `cm_artist_rank` metric the response uses a cached rank (overall or per-slice); other metrics compute position dynamically from `cm_artist_cache`. `obj` is `null` when no rank row exists.", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer", "minimum": 2, "maximum": 2147483647, "not": { "enum": [ 1 ] }, "description": "Chartmetric artist ID. Note: id=1 ('Various Artists') is rejected." }, "required": true, "description": "Chartmetric artist ID. Note: id=1 ('Various Artists') is rejected.", "examples": { "default": { "value": 2 } } }, { "name": "metric", "in": "query", "schema": { "type": "string", "enum": [ "cm_artist_rank", "sp_popularity", "sp_followers", "sp_monthly_listeners", "sp_listeners_to_followers_ratio", "sp_followers_to_listeners_ratio", "deezer_fans", "fs_likes", "fs_talks", "ins_followers", "ts_followers", "ts_retweets", "ycs_views", "ycs_subscribers", "ws_views", "soundcloud_followers", "bs_followers" ], "description": "Rank metric to use. One of `cm_artist_rank`, `sp_popularity`, `sp_followers`, `sp_monthly_listeners`, `sp_listeners_to_followers_ratio`, `sp_followers_to_listeners_ratio`, `deezer_fans`, `fs_likes`, `fs_talks`, `ins_followers`, `ts_followers`, `ts_retweets`, `ycs_views`, `ycs_subscribers`, `ws_views`, `soundcloud_followers`, `bs_followers`. Defaults to `cm_artist_rank` (Chartmetric overall artist rank)." }, "required": false, "description": "Rank metric to use. One of `cm_artist_rank`, `sp_popularity`, `sp_followers`, `sp_monthly_listeners`, `sp_listeners_to_followers_ratio`, `sp_followers_to_listeners_ratio`, `deezer_fans`, `fs_likes`, `fs_talks`, `ins_followers`, `ts_followers`, `ts_retweets`, `ycs_views`, `ycs_subscribers`, `ws_views`, `soundcloud_followers`, `bs_followers`. Defaults to `cm_artist_rank` (Chartmetric overall artist rank)." }, { "name": "code2", "in": "query", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2, "description": "Restrict to a single country (ISO 3166-1 alpha-2, e.g. 'US'). When omitted, no country filter is applied." }, "required": false, "description": "Restrict to a single country (ISO 3166-1 alpha-2, e.g. 'US'). When omitted, no country filter is applied." }, { "name": "genre", "in": "query", "schema": { "type": [ "integer", "null" ], "description": "Restrict to a single Chartmetric genre by ID. When omitted, no genre filter is applied." }, "required": false, "description": "Restrict to a single Chartmetric genre by ID. When omitted, no genre filter is applied." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": [ "object", "null" ], "properties": { "artist_rank": { "type": [ "integer", "null" ], "description": "Artist rank for the requested metric and slice." } } } }, "additionalProperties": false }, "examples": { "default": { "value": { "obj": { "artist_rank": 1 } } } } } } } } } }, "/api/artist/{id}/past-artist-rank": { "get": { "summary": "Artist Rank on Historical Date", "tags": [ "Artist" ], "operationId": "getArtistPastRank", "description": "Artist's rank on a specific past `date` (YYYY-MM-DD) for the given `metric`. Supported metric values: `cm_artist_rank` (single-row overall), `cm_artist_country_rank` (rows keyed by `code2`), `cm_artist_genre_rank` / `cm_artist_subgenre_rank` (rows keyed by `{genre_id, genre}`), or any other metric that flows through the stat-based COUNT fallback. Always returns an array.", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer", "minimum": 2, "maximum": 2147483647, "not": { "enum": [ 1 ] }, "description": "Chartmetric artist ID. Note: id=1 ('Various Artists') is rejected." }, "required": true, "description": "Chartmetric artist ID. Note: id=1 ('Various Artists') is rejected.", "examples": { "default": { "value": 2 } } }, { "name": "metric", "in": "query", "schema": { "type": "string", "enum": [ "cm_artist_rank", "cm_artist_country_rank", "cm_artist_genre_rank", "cm_artist_subgenre_rank", "sp_popularity", "sp_followers", "sp_monthly_listeners", "sp_listeners_to_followers_ratio", "sp_followers_to_listeners_ratio", "deezer_fans", "fs_likes", "fs_talks", "ins_followers", "ts_followers", "ts_retweets", "ycs_views", "ycs_subscribers", "ws_views", "soundcloud_followers", "bs_followers" ], "description": "Rank metric to use. One of `cm_artist_rank`, `cm_artist_country_rank`, `cm_artist_genre_rank`, `cm_artist_subgenre_rank`, `sp_popularity`, `sp_followers`, `sp_monthly_listeners`, `sp_listeners_to_followers_ratio`, `sp_followers_to_listeners_ratio`, `deezer_fans`, `fs_likes`, `fs_talks`, `ins_followers`, `ts_followers`, `ts_retweets`, `ycs_views`, `ycs_subscribers`, `ws_views`, `soundcloud_followers`, `bs_followers`. Defaults to `cm_artist_rank`.", "default": "cm_artist_rank" }, "required": false, "description": "Rank metric to use. One of `cm_artist_rank`, `cm_artist_country_rank`, `cm_artist_genre_rank`, `cm_artist_subgenre_rank`, `sp_popularity`, `sp_followers`, `sp_monthly_listeners`, `sp_listeners_to_followers_ratio`, `sp_followers_to_listeners_ratio`, `deezer_fans`, `fs_likes`, `fs_talks`, `ins_followers`, `ts_followers`, `ts_retweets`, `ycs_views`, `ycs_subscribers`, `ws_views`, `soundcloud_followers`, `bs_followers`. Defaults to `cm_artist_rank`." }, { "name": "date", "in": "query", "schema": { "type": "string", "format": "date", "description": "Historical date in ISO format (e.g. '2025-11-01'). Defaults to today. Data may not exist for every historical date.", "default": "2026-11-05" }, "required": false, "description": "Historical date in ISO format (e.g. '2025-11-01'). Defaults to today. Data may not exist for every historical date." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "array", "items": { "type": "object", "properties": { "artist_rank": { "type": [ "integer", "null" ], "description": "Artist rank on the requested historical date." }, "code2": { "type": [ "string", "null" ], "description": "Country code (ISO 3166-1 alpha-2). Only present for `cm_artist_country_rank`." }, "genre_id": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Chartmetric genre ID. Only present for `cm_artist_genre_rank` / `cm_artist_subgenre_rank`." }, "genre": { "type": [ "string", "null" ], "description": "Genre name. Only present for `cm_artist_genre_rank` / `cm_artist_subgenre_rank`." } } } } }, "required": [ "obj" ], "additionalProperties": false }, "examples": { "default": { "value": { "obj": [ { "artist_rank": 1, "genre_id": 188, "genre": "pop" }, { "artist_rank": 1, "genre_id": 419154, "genre": "uk pop" } ] } } } } } } } } }, "/api/artist/{id}/neighboring-artists": { "get": { "summary": "Neighboring Artists", "tags": [ "Artist" ], "operationId": "listArtistNeighboringArtists", "description": "Artists with adjacent rankings around this artist for the requested `metric`. Uses cursor-based pagination around the selected artist (half before, half after). Pass `type=genre` to filter by the artist genre cluster — in that branch the response wraps the artist list under `cluster_artists` alongside `tags` (cluster tag list). Without `type=genre` the response is a bare array. Per-row stats are sparsely populated depending on the artist — contract keeps rows permissive (`unknown(true)`). `genres` is a comma-joined string of genre names.", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer", "minimum": 2, "maximum": 2147483647, "not": { "enum": [ 1 ] }, "description": "Chartmetric artist ID. Note: id=1 ('Various Artists') is rejected." }, "required": true, "description": "Chartmetric artist ID. Note: id=1 ('Various Artists') is rejected.", "examples": { "default": { "value": 2 } } }, { "name": "metric", "in": "query", "schema": { "type": "string", "enum": [ "cm_artist_rank", "sp_popularity", "sp_followers", "sp_monthly_listeners", "sp_listeners_to_followers_ratio", "sp_followers_to_listeners_ratio", "deezer_fans", "fs_likes", "fs_talks", "ins_followers", "ts_followers", "ts_retweets", "ycs_views", "ycs_subscribers", "ws_views", "soundcloud_followers", "bs_followers" ], "description": "Rank metric to neighbor by. One of `cm_artist_rank`, `sp_popularity`, `sp_followers`, `sp_monthly_listeners`, `sp_listeners_to_followers_ratio`, `sp_followers_to_listeners_ratio`, `deezer_fans`, `fs_likes`, `fs_talks`, `ins_followers`, `ts_followers`, `ts_retweets`, `ycs_views`, `ycs_subscribers`, `ws_views`, `soundcloud_followers`, `bs_followers`. Defaults to `cm_artist_rank`.", "default": "cm_artist_rank" }, "required": false, "description": "Rank metric to neighbor by. One of `cm_artist_rank`, `sp_popularity`, `sp_followers`, `sp_monthly_listeners`, `sp_listeners_to_followers_ratio`, `sp_followers_to_listeners_ratio`, `deezer_fans`, `fs_likes`, `fs_talks`, `ins_followers`, `ts_followers`, `ts_retweets`, `ycs_views`, `ycs_subscribers`, `ws_views`, `soundcloud_followers`, `bs_followers`. Defaults to `cm_artist_rank`." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "maximum": 100, "description": "Maximum number of neighboring artists to return. Defaults to 10, max 100.", "default": 10 }, "required": false, "description": "Maximum number of neighboring artists to return. Defaults to 10, max 100." }, { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "genre" ], "description": "Set to `genre` to apply genre-clustering. When set, the response wraps the artist list under `cluster_artists` alongside `tags`." }, "required": false, "description": "Set to `genre` to apply genre-clustering. When set, the response wraps the artist list under `cluster_artists` alongside `tags`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Chartmetric artist ID of the neighboring artist." }, "name": { "type": [ "string", "null" ], "description": "Artist name." }, "pronoun": { "type": [ "string", "null" ], "description": "Artist's pronouns." }, "band": { "type": [ "boolean", "null" ], "description": "True for bands, false for solo artists, null when unknown." }, "image_url": { "type": [ "string", "null" ], "description": "Artist image URL." }, "preview_url": { "type": [ "string", "null" ], "description": "Artist's preview audio URL." }, "code2": { "type": [ "string", "null" ], "description": "Artist country (ISO 3166-1 alpha-2)." }, "cm_tag": { "type": [ "array", "null" ], "items": {}, "description": "Flattened list of Chartmetric genre IDs." }, "cm_tag_rank": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "cm_tag": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 2147483647 }, { "type": "string" } ], "nullable": true, "description": "Chartmetric tag (genre) ID." }, "rank": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Artist's rank within the genre." }, "name": { "type": [ "string", "null" ], "description": "Genre name." }, "primary": { "type": "boolean", "description": "True for the artist primary genre." } } }, "description": "List of artist's per-genre ranks." }, "position": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Artist's position relative to the requested neighbor metric." }, "country_rank": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Artist's rank within their country." }, "country_rank_code2": { "type": [ "string", "null" ], "description": "Country slice for `country_rank`." }, "genres": { "type": [ "string", "null" ], "description": "Comma-joined list of genre names." }, "sp_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Spotify follower count." }, "sp_monthly_listeners": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Spotify monthly listener count." }, "sp_popularity": { "type": [ "number", "null" ], "format": "float", "description": "Spotify popularity score (0–100)." }, "sp_listeners_to_followers_ratio": { "type": [ "number", "null" ], "format": "float", "description": "Ratio of Spotify monthly listeners to Spotify followers." }, "sp_followers_to_listeners_ratio": { "type": [ "number", "null" ], "format": "float", "description": "Ratio of Spotify followers to Spotify monthly listeners." }, "deezer_fans": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Deezer fan count." }, "fs_likes": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Facebook page-like count." }, "fs_talks": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Facebook people-talking-about count: users discussing or interacting with the page." }, "ins_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Instagram follower count." }, "ts_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Twitter/X follower count." }, "ts_retweets": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Twitter/X retweet count." }, "ycs_views": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "YouTube channel total view count." }, "ycs_subscribers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "YouTube channel subscriber count." }, "youtube_daily_video_views": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "YouTube daily video view count." }, "youtube_monthly_video_views": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "YouTube monthly video view count." }, "ws_views": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Wikipedia page-view count." }, "soundcloud_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "SoundCloud follower count." }, "bs_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Bandsintown follower count." }, "tiktok_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "TikTok follower count." }, "tiktok_likes": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "TikTok total like count." }, "cm_artist_rank": { "type": [ "number", "null" ], "format": "float", "description": "Global Chartmetric artist rank (1 is highest)." } } } }, { "type": "object", "properties": { "cluster_artists": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Chartmetric artist ID of the neighboring artist." }, "name": { "type": [ "string", "null" ], "description": "Artist name." }, "pronoun": { "type": [ "string", "null" ], "description": "Artist's pronouns." }, "band": { "type": [ "boolean", "null" ], "description": "True for bands, false for solo artists, null when unknown." }, "image_url": { "type": [ "string", "null" ], "description": "Artist image URL." }, "preview_url": { "type": [ "string", "null" ], "description": "Artist's preview audio URL." }, "code2": { "type": [ "string", "null" ], "description": "Artist country (ISO 3166-1 alpha-2)." }, "cm_tag": { "type": [ "array", "null" ], "items": {}, "description": "Flattened list of Chartmetric genre IDs." }, "cm_tag_rank": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "cm_tag": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 2147483647 }, { "type": "string" } ], "nullable": true, "description": "Chartmetric tag (genre) ID." }, "rank": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Artist's rank within the genre." }, "name": { "type": [ "string", "null" ], "description": "Genre name." }, "primary": { "type": "boolean", "description": "True for the artist primary genre." } } }, "description": "List of artist's per-genre ranks." }, "position": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Artist's position relative to the requested neighbor metric." }, "country_rank": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Artist's rank within their country." }, "country_rank_code2": { "type": [ "string", "null" ], "description": "Country slice for `country_rank`." }, "genres": { "type": [ "string", "null" ], "description": "Comma-joined list of genre names." }, "sp_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Spotify follower count." }, "sp_monthly_listeners": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Spotify monthly listener count." }, "sp_popularity": { "type": [ "number", "null" ], "format": "float", "description": "Spotify popularity score (0–100)." }, "sp_listeners_to_followers_ratio": { "type": [ "number", "null" ], "format": "float", "description": "Ratio of Spotify monthly listeners to Spotify followers." }, "sp_followers_to_listeners_ratio": { "type": [ "number", "null" ], "format": "float", "description": "Ratio of Spotify followers to Spotify monthly listeners." }, "deezer_fans": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Deezer fan count." }, "fs_likes": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Facebook page-like count." }, "fs_talks": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Facebook people-talking-about count: users discussing or interacting with the page." }, "ins_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Instagram follower count." }, "ts_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Twitter/X follower count." }, "ts_retweets": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Twitter/X retweet count." }, "ycs_views": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "YouTube channel total view count." }, "ycs_subscribers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "YouTube channel subscriber count." }, "youtube_daily_video_views": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "YouTube daily video view count." }, "youtube_monthly_video_views": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "YouTube monthly video view count." }, "ws_views": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Wikipedia page-view count." }, "soundcloud_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "SoundCloud follower count." }, "bs_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Bandsintown follower count." }, "tiktok_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "TikTok follower count." }, "tiktok_likes": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "TikTok total like count." }, "cm_artist_rank": { "type": [ "number", "null" ], "format": "float", "description": "Global Chartmetric artist rank (1 is highest)." } } }, "description": "List of neighboring artists in the same genre cluster." }, "tags": { "type": [ "object", "null" ], "properties": {}, "description": "Cluster genre tags (e.g. `{ top_genres: [...] }`)." } } } ] } }, "additionalProperties": false }, "examples": { "default": { "value": { "obj": [ { "id": 53722, "name": "Tharyk", "pronoun": null, "band": false, "image_url": "https://i.scdn.co/image/481216e68d8cdc2dad2ba9c64e4d9fcc98b5192a", "preview_url": null, "code2": "US", "cm_tag": [ 9847, 419163 ], "cm_tag_rank": [ { "cm_tag": 9847, "rank": 1234, "name": "pop", "primary": true }, { "cm_tag": 419163, "rank": 2345, "name": "dance pop" } ], "position": 117, "country_rank": 542, "country_rank_code2": "US", "genres": "pop, dance pop" } ] } } } } } } } } }, "/api/artist/{id}/market-coverage-views/youtube": { "get": { "summary": "YouTube Views & Market Coverage", "tags": [ "Artist" ], "operationId": "listArtistYoutubeMarketCoverage", "description": "Artist's YouTube-for-Artist views snapshot split by top cities / countries, alongside competitor `marketInsights` and the artist's aggregate monthly views for the requested `date`. Each insight entry carries a 28-day `trend` series. Cities are decorated with `continent`. Market coverage for top 100 cities is available only for dates on/after 2024-05-24.", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer", "minimum": 2, "maximum": 2147483647, "not": { "enum": [ 1 ] }, "description": "Chartmetric artist ID. Note: id=1 ('Various Artists') is rejected." }, "required": true, "description": "Chartmetric artist ID. Note: id=1 ('Various Artists') is rejected.", "examples": { "default": { "value": 2 } } }, { "name": "date", "in": "query", "schema": { "type": "string", "format": "date", "description": "Snapshot date in ISO format (e.g. '2024-12-01'). Top-100-cities coverage is available only on/after 2024-05-24. When omitted, returns the most recent snapshot." }, "required": false, "description": "Snapshot date in ISO format (e.g. '2024-12-01'). Top-100-cities coverage is available only on/after 2024-05-24. When omitted, returns the most recent snapshot." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "object", "properties": { "insights": { "type": "object", "properties": { "cities": { "type": "array", "items": { "type": "object", "properties": { "rank": { "type": [ "integer", "null" ], "description": "1-based rank of this location among insight rows." }, "value": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Monthly view count or weight for the location." }, "timestp": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Snapshot date (ISO 8601)." }, "params_id": { "type": [ "string", "null" ], "description": "Internal lookup ID for the location row." }, "name": { "type": [ "string", "null" ], "description": "City or country name." }, "lat": { "type": [ "number", "null" ], "format": "float", "description": "Latitude of the location." }, "lng": { "type": [ "number", "null" ], "format": "float", "description": "Longitude of the location." }, "code2": { "type": [ "string", "null" ], "description": "Country code (ISO 3166-1 alpha-2)." }, "city_id": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Chartmetric city ID." }, "current_max_count": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Maximum value across all artists at this location." }, "region": { "type": [ "string", "null" ], "description": "Region — `CITY` or `COUNTRY`." }, "market_max_cm_artist_id": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 2147483647 }, { "type": "string" } ], "nullable": true, "description": "Chartmetric artist ID with the maximum value at this location." }, "market_max_artist_name": { "type": [ "string", "null" ], "description": "Name of the artist with the maximum value at this location." }, "continent": { "type": [ "string", "null" ], "description": "Continent code (e.g. `NA`, `EU`)." }, "trend": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "timestp": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Date of the trend point (ISO 8601)." }, "monthlyViews": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Monthly views at this date." } } }, "description": "28-day rolling trend series of monthly views." } } }, "description": "Top cities by the artist's YouTube monthly views." }, "countries": { "type": "array", "items": { "type": "object", "properties": { "rank": { "type": [ "integer", "null" ], "description": "1-based rank of this location among insight rows." }, "value": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Monthly view count or weight for the location." }, "timestp": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Snapshot date (ISO 8601)." }, "params_id": { "type": [ "string", "null" ], "description": "Internal lookup ID for the location row." }, "name": { "type": [ "string", "null" ], "description": "City or country name." }, "lat": { "type": [ "number", "null" ], "format": "float", "description": "Latitude of the location." }, "lng": { "type": [ "number", "null" ], "format": "float", "description": "Longitude of the location." }, "code2": { "type": [ "string", "null" ], "description": "Country code (ISO 3166-1 alpha-2)." }, "city_id": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Chartmetric city ID." }, "current_max_count": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Maximum value across all artists at this location." }, "region": { "type": [ "string", "null" ], "description": "Region — `CITY` or `COUNTRY`." }, "market_max_cm_artist_id": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 2147483647 }, { "type": "string" } ], "nullable": true, "description": "Chartmetric artist ID with the maximum value at this location." }, "market_max_artist_name": { "type": [ "string", "null" ], "description": "Name of the artist with the maximum value at this location." }, "continent": { "type": [ "string", "null" ], "description": "Continent code (e.g. `NA`, `EU`)." }, "trend": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "timestp": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Date of the trend point (ISO 8601)." }, "monthlyViews": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Monthly views at this date." } } }, "description": "28-day rolling trend series of monthly views." } } }, "description": "Top countries by the artist's YouTube monthly views." } }, "description": "Latest snapshot of the artist's YouTube views by city/country." }, "marketInsights": { "type": "object", "properties": { "marketCities": { "type": "array", "items": { "type": "object", "properties": { "rank": { "type": [ "integer", "null" ], "description": "1-based rank of this location among insight rows." }, "value": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Monthly view count or weight for the location." }, "timestp": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Snapshot date (ISO 8601)." }, "params_id": { "type": [ "string", "null" ], "description": "Internal lookup ID for the location row." }, "name": { "type": [ "string", "null" ], "description": "City or country name." }, "lat": { "type": [ "number", "null" ], "format": "float", "description": "Latitude of the location." }, "lng": { "type": [ "number", "null" ], "format": "float", "description": "Longitude of the location." }, "code2": { "type": [ "string", "null" ], "description": "Country code (ISO 3166-1 alpha-2)." }, "city_id": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Chartmetric city ID." }, "current_max_count": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Maximum value across all artists at this location." }, "region": { "type": [ "string", "null" ], "description": "Region — `CITY` or `COUNTRY`." }, "market_max_cm_artist_id": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 2147483647 }, { "type": "string" } ], "nullable": true, "description": "Chartmetric artist ID with the maximum value at this location." }, "market_max_artist_name": { "type": [ "string", "null" ], "description": "Name of the artist with the maximum value at this location." }, "continent": { "type": [ "string", "null" ], "description": "Continent code (e.g. `NA`, `EU`)." }, "trend": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "timestp": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Date of the trend point (ISO 8601)." }, "monthlyViews": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Monthly views at this date." } } }, "description": "28-day rolling trend series of monthly views." } } }, "description": "Cities ordered by the artist's market-coverage weight (artist views / market max views)." }, "marketCountries": { "type": "array", "items": { "type": "object", "properties": { "rank": { "type": [ "integer", "null" ], "description": "1-based rank of this location among insight rows." }, "value": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Monthly view count or weight for the location." }, "timestp": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Snapshot date (ISO 8601)." }, "params_id": { "type": [ "string", "null" ], "description": "Internal lookup ID for the location row." }, "name": { "type": [ "string", "null" ], "description": "City or country name." }, "lat": { "type": [ "number", "null" ], "format": "float", "description": "Latitude of the location." }, "lng": { "type": [ "number", "null" ], "format": "float", "description": "Longitude of the location." }, "code2": { "type": [ "string", "null" ], "description": "Country code (ISO 3166-1 alpha-2)." }, "city_id": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Chartmetric city ID." }, "current_max_count": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Maximum value across all artists at this location." }, "region": { "type": [ "string", "null" ], "description": "Region — `CITY` or `COUNTRY`." }, "market_max_cm_artist_id": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 2147483647 }, { "type": "string" } ], "nullable": true, "description": "Chartmetric artist ID with the maximum value at this location." }, "market_max_artist_name": { "type": [ "string", "null" ], "description": "Name of the artist with the maximum value at this location." }, "continent": { "type": [ "string", "null" ], "description": "Continent code (e.g. `NA`, `EU`)." }, "trend": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "timestp": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Date of the trend point (ISO 8601)." }, "monthlyViews": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Monthly views at this date." } } }, "description": "28-day rolling trend series of monthly views." } } }, "description": "Countries ordered by the artist's market-coverage weight (artist views / market max views)." } }, "description": "Artist's market coverage relative to the location maxima." }, "artistTotalViews": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Aggregate monthly YouTube views across all locations for the artist." } } } }, "additionalProperties": false }, "examples": { "default": { "value": { "obj": { "insights": { "cities": [ { "rank": 1, "value": 12345678, "timestp": "2025-01-15", "params_id": "207359", "name": "Los Angeles", "lat": 34.05223, "lng": -118.24368, "code2": "US", "city_id": 207359, "current_max_count": "15000000", "region": "CITY", "market_max_cm_artist_id": 12345, "market_max_artist_name": "Example Competitor", "continent": "NA", "trend": [ { "timestp": "2025-01-01", "monthlyViews": 10000000 } ] } ], "countries": [ { "rank": 1, "value": 50000000, "timestp": "2025-01-15", "name": "United States", "code2": "US", "region": "COUNTRY" } ] }, "marketInsights": { "marketCities": [], "marketCountries": [] }, "artistTotalViews": 1234567890 } } } } } } } } } }, "/api/artist/{id}/tvmaze": { "get": { "summary": "TV Show Appearances", "tags": [ "Artist" ], "operationId": "listArtistTvShows", "description": "TV show appearances for this artist, sourced from TVmaze. `people` is an array (usually 0-1 entries) containing the tv_maze_artist row. `shows` is an array of `{ title, as, url, year, episodes, show_details }` — `episodes` is an aggregated JSON array of episode rows, `show_details` is the full show row as JSON. The apidoc example types `people` as a single object; the handler returns an array because `db.any(...)` was used on the lookup.", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer", "minimum": 2, "maximum": 2147483647, "not": { "enum": [ 1 ] }, "description": "Chartmetric artist ID. Note: id=1 ('Various Artists') is rejected." }, "required": true, "description": "Chartmetric artist ID. Note: id=1 ('Various Artists') is rejected.", "examples": { "default": { "value": 2 } } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "object", "properties": { "people": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "TVmaze person ID." }, "name": { "type": [ "string", "null" ], "description": "Artist/person name." }, "gender": { "type": [ "integer", "null" ], "description": "TVmaze gender code." }, "image": { "type": [ "string", "null" ], "description": "Person image URL." }, "date_of_birth": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Date of birth (ISO 8601)." }, "date_of_death": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Date of death (ISO 8601), if applicable." }, "country_code": { "type": [ "string", "null" ], "description": "Person country (ISO 3166-1 alpha-2)." }, "tv_maze_url": { "type": [ "string", "null" ], "description": "TVmaze URL for the person." }, "cm_artist": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Linked Chartmetric artist ID." }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Date the person record was created in Chartmetric." }, "modified_at": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Date the person record was last modified in Chartmetric." } } }, "description": "TVmaze person rows linked to this Chartmetric artist (usually 0 or 1)." }, "shows": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": [ "string", "null" ], "description": "Show title." }, "as": { "type": [ "string", "null" ], "description": "Role description (e.g. `Guest starring as Mick`)." }, "url": { "type": [ "string", "null" ], "description": "TVmaze URL for the show." }, "year": { "type": [ "string", "null" ], "description": "Show year." }, "episodes": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "TVmaze episode ID." }, "title": { "type": [ "string", "null" ], "description": "Episode title." }, "url": { "type": [ "string", "null" ], "description": "TVmaze URL for the episode." }, "date": { "type": [ "string", "null" ], "description": "Episode air date (free-form string from TVmaze)." } } }, "description": "Episodes in which the artist appears." }, "show_details": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "TVmaze show ID." }, "name": { "type": [ "string", "null" ], "description": "Show name." }, "genres": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Show genres." }, "runtime": { "type": [ "integer", "null" ], "description": "Show runtime in minutes." }, "premiered": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Premiere date (ISO 8601)." }, "officialsite": { "type": [ "string", "null" ], "description": "Show's official website URL." }, "rating": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "TVmaze rating." }, "image": { "type": [ "string", "null" ], "description": "Show cover image URL." }, "summary": { "type": [ "string", "null" ], "description": "HTML show summary." }, "tv_maze_url": { "type": [ "string", "null" ], "description": "TVmaze URL for the show." }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Date the show record was created in Chartmetric." }, "modified_at": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Date the show record was last modified in Chartmetric." } }, "description": "Full show metadata." } } }, "description": "TV shows in which the artist appears, with per-show episode lists and details." } }, "required": [ "people", "shows" ] } }, "additionalProperties": false }, "examples": { "default": { "value": { "obj": { "people": [ { "id": 64614, "name": "Ed Sheeran", "gender": 1, "image": "http://static.tvmaze.com/uploads/images/original_untouched/13/34295.jpg", "date_of_birth": "1991-02-01T08:00:00.000Z", "date_of_death": null, "country_code": "GB", "tv_maze_url": "http://www.tvmaze.com/people/64614/ed-sheeran", "cm_artist": 3648, "created_at": null, "modified_at": "2020-11-12T18:09:59.730Z" } ], "shows": [ { "title": "Modern Love", "as": "Guest starring as Mick", "url": "https://www.tvmaze.com/shows/37120/modern-love", "year": "2019", "episodes": [ { "id": 1718414, "title": "Episode 1x07: Hers Was a World of One", "url": "https://www.tvmaze.com/episodes/1718414/modern-love-1x07-hers-was-a-world-of-one", "date": "Oct 18, 2019" } ], "show_details": { "id": 37120, "name": "Modern Love", "genres": [ "Comedy", "Romance" ], "runtime": null, "premiered": "2019-10-18T07:00:00.000Z", "officialsite": "https://www.amazon.com/dp/B07VMF8TL9/", "rating": "7.5", "image": "http://static.tvmaze.com/uploads/images/original_untouched/216/540345.jpg", "summary": "

An unlikely friendship...

", "tv_maze_url": "http://www.tvmaze.com/shows/37120/modern-love", "created_at": "2020-09-23T22:03:25.001Z", "modified_at": "2020-11-18T00:36:13.551Z" } } ] } } } } } } } } } }, "/api/artist/{id}/career": { "get": { "summary": "Career History", "tags": [ "Artist" ], "operationId": "getArtistCareer", "description": "Historical career-stage snapshots for an artist (`stage`/`stage_score` + `momentum`/`momentum_score` per `timestp`, descending by date). Structure parallels `career_status` from the artist metadata endpoint. Data pre 2023-05-12 is only available with `legacy=true`; data after 2023-09-20 is only available with `legacy=false`. Legacy support ends 2023-10-18.", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer", "minimum": 2, "maximum": 2147483647, "not": { "enum": [ 1 ] }, "description": "Chartmetric artist ID. Note: id=1 ('Various Artists') is rejected." }, "required": true, "description": "Chartmetric artist ID. Note: id=1 ('Various Artists') is rejected.", "examples": { "default": { "value": 2 } } }, { "name": "since", "in": "query", "schema": { "type": "string", "format": "date", "description": "Start of the date range in ISO format (e.g. '2025-11-01'). When null, no lower bound is applied." }, "required": false, "description": "Start of the date range in ISO format (e.g. '2025-11-01'). When null, no lower bound is applied." }, { "name": "until", "in": "query", "schema": { "type": "string", "format": "date", "description": "End of the date range in ISO format (e.g. '2025-11-15'). When null, no upper bound is applied." }, "required": false, "description": "End of the date range in ISO format (e.g. '2025-11-15'). When null, no upper bound is applied." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Maximum number of career-history rows to return. Defaults to 10.", "default": 10 }, "required": false, "description": "Maximum number of career-history rows to return. Defaults to 10." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "description": "Number of rows to skip from the start of the result set. Defaults to 0." }, "required": false, "description": "Number of rows to skip from the start of the result set. Defaults to 0." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "array", "items": { "type": "object", "properties": { "timestp": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Date of the career snapshot (`YYYY-MM-DD`)." }, "stage": { "type": [ "string", "null" ], "description": "Career stage. Values in order: `undiscovered`, `developing`, `mid-level`, `mainstream`, `superstar`, `legendary`." }, "stage_score": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Score (0–100) representing relative progression through the current `stage`." }, "momentum": { "type": [ "string", "null" ], "description": "Recent momentum. Values in order: `decline`, `gradual decline`, `steady`, `growth`, `explosive growth`." }, "momentum_score": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Score (0–100) representing strength of the current `momentum`." } } } } }, "required": [ "obj" ], "additionalProperties": false }, "examples": { "default": { "value": { "obj": [ { "timestp": "2023-07-26", "stage": "superstar", "stage_score": 68, "momentum": "decline", "momentum_score": 100 } ] } } } } } } } } }, "/api/artist/{id}/milestones": { "get": { "summary": "Milestones", "tags": [ "Artist" ], "operationId": "listArtistMilestones", "description": "Milestone insights for an artist — discrete events flagged by the internal feed system (chart debuts, playlist adds, stat thresholds, etc.). Each insight carries a human-readable `summary`, `platform`, and `stars` importance (1-5). Paginated via `limit`/`offset`; filter by `stars`, `fromDaysAgo`, `group`, `grouped`, `sortColumn`, `sortOrderDesc`, `platforms`. Top-level is `{ insights, count }` where `count` is the total across all filters.", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer", "minimum": 2, "maximum": 2147483647, "not": { "enum": [ 1 ] }, "description": "Chartmetric artist ID. Note: id=1 ('Various Artists') is rejected." }, "required": true, "description": "Chartmetric artist ID. Note: id=1 ('Various Artists') is rejected.", "examples": { "default": { "value": 2 } } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "description": "Maximum number of milestones to return. Defaults to 100.", "default": 100 }, "required": false, "description": "Maximum number of milestones to return. Defaults to 100." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, "required": false, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, { "name": "stars[]", "in": "query", "schema": { "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 5 }, "description": "Restrict to milestones with star counts in this set (e.g. `[1, 2, 3]`). Each value is between 1 and 5." }, "required": false, "description": "Restrict to milestones with star counts in this set (e.g. `[1, 2, 3]`). Each value is between 1 and 5." }, { "name": "fromDaysAgo", "in": "query", "schema": { "type": "integer", "description": "Restrict to milestones from the last N days, counted from today." }, "required": false, "description": "Restrict to milestones from the last N days, counted from today." }, { "name": "sortColumn", "in": "query", "schema": { "type": "string", "enum": [ "date", "stars" ], "description": "Column to sort milestones by. One of `date`, `stars`. Defaults to `date`.", "default": "date" }, "required": false, "description": "Column to sort milestones by. One of `date`, `stars`. Defaults to `date`." }, { "name": "sortOrderDesc", "in": "query", "schema": { "type": "boolean", "description": "If true, sort descending by `sortColumn`. Defaults to true.", "default": true }, "required": false, "description": "If true, sort descending by `sortColumn`. Defaults to true." }, { "name": "platforms[]", "in": "query", "schema": { "type": "array", "items": { "type": "string", "enum": [ "amazon", "apple_music", "beatport", "chartmetric", "deezer", "instagram", "itunes", "pandora", "shazam", "soundcloud", "spotify", "tiktok", "youtube" ], "title": "Platform name" }, "description": "Restrict to milestones from these platforms (e.g. `Spotify`, `YouTube`)." }, "required": false, "description": "Restrict to milestones from these platforms (e.g. `Spotify`, `YouTube`)." }, { "name": "grouped", "in": "query", "schema": { "type": "boolean", "description": "If true, return only the top milestone per group (e.g. one per chart). Defaults to false." }, "required": false, "description": "If true, return only the top milestone per group (e.g. one per chart). Defaults to false." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "object", "properties": { "insights": { "type": "array", "items": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 2147483647 }, { "type": "string" } ], "nullable": true, "description": "Milestone insight ID." }, "date": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Date the milestone occurred (ISO 8601)." }, "summary": { "type": [ "string", "null" ], "description": "Human-readable description of the milestone, matching what is shown on the artist profile page." }, "artist_name": { "type": [ "string", "null" ], "description": "Artist's display name." }, "track_name": { "type": [ "string", "null" ], "description": "Track name, when applicable." }, "platform": { "type": [ "string", "null" ], "description": "Platform on which the milestone was reached (e.g. `Spotify`, `YouTube`)." }, "stars": { "type": [ "integer", "null" ], "description": "Importance rating (1-5)." }, "group_size": { "anyOf": [ { "type": [ "integer", "null" ] }, { "type": "string" } ], "description": "Number of milestones aggregated into the same group, when grouping is applied." } } }, "description": "Milestone insight rows for the requested filters." }, "count": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "string" } ], "nullable": true, "description": "Total number of milestones matching the filters across all pages." } }, "required": [ "insights" ] } }, "additionalProperties": false }, "examples": { "default": { "value": { "obj": { "insights": [ { "id": 1754976786, "date": "2024-04-29", "summary": "Run added to Spotify Top 50 - Vietnam at position 5 with 90.5K followers.", "artist_name": "BTS", "track_name": "Run", "platform": "Spotify", "stars": 4 } ], "count": 3126 } } } } } } } } } }, "/api/artist/{id}/noteworthy-insights": { "get": { "summary": "Noteworthy Insights", "tags": [ "Artist" ], "operationId": "listArtistNoteworthyInsights", "description": "Recent noteworthy-insight rows for an artist — statistical outliers detected by the internal insights pipeline (daily or weekly). Each row includes a `variant` tier (`very-low`/`low`/`high`/`very-high`, or `negative-positive` for weekly negative→positive swings), the observed metric and its Dx1/Dx2 deltas, plus hydrated `targetName`/`targetImageUrl`/`code2` from `cm_artist_cache`.", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer", "minimum": 2, "maximum": 2147483647, "not": { "enum": [ 1 ] }, "description": "Chartmetric artist ID. Note: id=1 ('Various Artists') is rejected." }, "required": true, "description": "Chartmetric artist ID. Note: id=1 ('Various Artists') is rejected.", "examples": { "default": { "value": 2 } } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "description": "Maximum number of insights to return. Defaults to 5.", "default": 5 }, "required": false, "description": "Maximum number of insights to return. Defaults to 5." }, { "name": "fromDaysAgo", "in": "query", "schema": { "type": "integer", "minimum": 1, "description": "Restrict to insights from the last N days, counted from today. Defaults to 28, min 1.", "default": 28 }, "required": false, "description": "Restrict to insights from the last N days, counted from today. Defaults to 28, min 1." }, { "name": "insightType", "in": "query", "schema": { "type": "string", "enum": [ "daily", "weekly" ], "description": "Insight cadence. One of `daily`, `weekly`. Defaults to `daily`.", "default": "daily" }, "required": false, "description": "Insight cadence. One of `daily`, `weekly`. Defaults to `daily`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "array", "items": { "type": "object", "properties": { "insight": { "type": [ "string", "null" ], "description": "Insight sentence as a template, not display-ready text. `@@@@@` stands in for the target name and `DDDDD` for the insight date; consumers substitute them with `targetName` and `insightDate` before display. `@@@@@` appears in every row; `DDDDD` only in `insightType=daily` rows — weekly rows open with \"Last week,\" and carry no date token (e.g. daily: \"@@@@@ attained 93,203 new New Spotify Followers on DDDDD, marking a 97.8% increase from their regular growth.\"; weekly: \"Last week, @@@@@ saw a 12,068 increase in Spotify Followers, reflecting a 75.3% rise over the average weekly growth.\"). Clients that want their own phrasing can ignore this field and build text from `variant`, `metricName`, `metricDx1`, `metricDx2`, `targetName` and `insightDate` instead." }, "variant": { "type": [ "string", "null" ], "description": "Insight tier — `very-low`, `low`, `high`, `very-high`, or `negative-positive` for weekly negative→positive swings." }, "insightType": { "type": [ "string", "null" ], "description": "Insight cadence — `daily` or `weekly`." }, "metricName": { "type": [ "string", "null" ], "description": "Metric the insight applies to (e.g. `sp_followers`)." }, "insightId": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 2147483647 }, { "type": "string" } ], "nullable": true, "description": "Insight row ID." }, "target": { "type": [ "string", "null" ], "description": "Target entity type — `cm_artist` for this endpoint." }, "targetId": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 2147483647 }, { "type": "string" } ], "nullable": true, "description": "Chartmetric ID of the target artist." }, "targetName": { "type": [ "string", "null" ], "description": "Target artist's name." }, "targetImageUrl": { "type": [ "string", "null" ], "description": "Target artist's image URL." }, "title": { "type": [ "string", "null" ], "description": "Display title for the insight." }, "insightDate": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Date the insight was triggered (ISO 8601)." }, "insightDateMinus7Days": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Reference date 7 days prior to `insightDate`." }, "graphImageUrl": { "type": [ "string", "null" ], "description": "S3 URL of the rendered insight graph." }, "code2": { "type": [ "string", "null" ], "description": "Country code (ISO 3166-1 alpha-2), when the insight is country-scoped." }, "platform": { "type": [ "string", "null" ], "description": "Platform of the insight (e.g. `Spotify`, `YouTube`)." }, "categories": { "type": [ "array", "null" ], "items": {}, "description": "List of insight category labels." }, "metricDx1": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Absolute metric value at `insightDate`." }, "metricDx2": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Growth ratio versus `insightDateMinus7Days` (multiply by 100 to get percent)." } } } } }, "required": [ "obj" ], "additionalProperties": false }, "examples": { "default": { "value": { "obj": [ { "variant": "very-low", "insightType": "daily", "metricName": "sp_followers", "insightId": 6765723, "target": "cm_artist", "targetId": "5596", "targetName": "Billie Eilish", "targetImageUrl": "https://i.scdn.co/image/ab67616100005174d8b9980db67272cb4d2c3daf", "insightDate": "2024-10-19T07:00:00.000Z", "insightDateMinus7Days": "2024-10-12T00:00:00.000Z", "graphImageUrl": "https://chartmetric-public.s3.us-west-2.amazonaws.com/noteworthy_insights/daily/dashboard/2024-10-19/cm_artist/5596/sp_followers.jpeg", "metricDx1": 93203, "metricDx2": 0.9780343385895287 } ] } } } } } } } } }, "/api/artist/{id}/{status}/events": { "get": { "summary": "Live Events", "tags": [ "Artist" ], "operationId": "listArtistEvents", "description": "Live events (concerts, festivals, performances) for an artist. The required `fromDaysAgo` / `toDaysAgo` pair is the filter that decides what comes back — `status` (`current` or `past`) only sets the sort direction, so widen the window rather than switching `status` when a call returns fewer events than expected. `type` (`concert` or `festival`) takes a single value and defaults to `concert` when omitted, for backward compatibility; a festival-heavy artist therefore reads as empty unless `type=festival` is passed, and covering both types takes one call each. `GET /api/artist/{id}/venues` applies neither a date window nor a type filter, which is why its counts are routinely higher than a default call here. Events come from the ES `cm_live_event` index, hydrated with jambase/songkick/seatgeek/ticketmaster URLs, venue details, and pricing (when available from seatgeek or ticketmaster). `price_trend` is a seatgeek-only 28-day average-price series; non-seatgeek sources return `[]`. `event_name` suffix (e.g. ` (cancelled)`) reflects the event status.", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer", "minimum": 2, "maximum": 2147483647, "not": { "enum": [ 1 ] }, "description": "Chartmetric artist ID. Note: id=1 ('Various Artists') is rejected." }, "required": true, "description": "Chartmetric artist ID. Note: id=1 ('Various Artists') is rejected.", "examples": { "default": { "value": 2 } } }, { "name": "status", "in": "path", "schema": { "type": "string", "enum": [ "current", "past" ], "description": "Sort direction, not a filter. One of `current`, `past` — `current` sorts ascending, `past` descending. The date range comes from `fromDaysAgo` / `toDaysAgo`." }, "required": true, "description": "Sort direction, not a filter. One of `current`, `past` — `current` sorts ascending, `past` descending. The date range comes from `fromDaysAgo` / `toDaysAgo`.", "examples": { "default": { "value": "current" } } }, { "name": "fromDaysAgo", "in": "query", "schema": { "type": "integer", "description": "Number of days ago marking the start of the event window. Use a negative value to point into the future. Together with `toDaysAgo` this is what filters the events — widen the window, not `status`, when fewer events come back than expected." }, "required": true, "description": "Number of days ago marking the start of the event window. Use a negative value to point into the future. Together with `toDaysAgo` this is what filters the events — widen the window, not `status`, when fewer events come back than expected.", "examples": { "default": { "value": 1 } } }, { "name": "toDaysAgo", "in": "query", "schema": { "type": "integer", "description": "Number of days ago marking the end of the event window. Use a negative value to point into the future. Together with `fromDaysAgo` this is what filters the events." }, "required": true, "description": "Number of days ago marking the end of the event window. Use a negative value to point into the future. Together with `fromDaysAgo` this is what filters the events.", "examples": { "default": { "value": 1 } } }, { "name": "cityId", "in": "query", "schema": { "type": [ "integer", "null" ], "description": "Optional Chartmetric city ID to filter events to a single city." }, "required": false, "description": "Optional Chartmetric city ID to filter events to a single city." }, { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "concert", "festival" ], "description": "Optional event type filter. One of `concert`, `festival`, single-valued. Defaults to `concert` when omitted, for backward compatibility, so an artist whose history is mostly festivals reads as empty unless `festival` is passed; covering both types takes one call each.", "default": "concert" }, "required": false, "description": "Optional event type filter. One of `concert`, `festival`, single-valued. Defaults to `concert` when omitted, for backward compatibility, so an artist whose history is mostly festivals reads as empty unless `festival` is passed; covering both types takes one call each." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Maximum number of events to return. Defaults to 10, max 100.", "default": 10 }, "required": false, "description": "Maximum number of events to return. Defaults to 10, max 100." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, "required": false, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Chartmetric event ID." }, "event_name": { "type": [ "string", "null" ], "description": "Event name. Status suffix appended for non-scheduled events (e.g. ` (cancelled)`)." }, "jambase_event_url": { "type": [ "string", "null" ], "description": "JamBase URL for the event." }, "songkick_event_url": { "type": [ "string", "null" ], "description": "Songkick URL for the event." }, "seatgeek_event_url": { "type": [ "string", "null" ], "description": "SeatGeek URL for the event." }, "ticketmaster_event_url": { "type": [ "string", "null" ], "description": "Ticketmaster URL for the event." }, "image_url": { "type": [ "string", "null" ], "description": "Event image URL." }, "type": { "type": [ "string", "null" ], "description": "Event type (e.g. `Concert`, `Festival`)." }, "start_date": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Event start date (ISO 8601)." }, "end_date": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Event end date (ISO 8601)." }, "venue_id": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Chartmetric venue ID." }, "venue_name": { "type": [ "string", "null" ], "description": "Venue name." }, "venue_url": { "type": [ "string", "null" ], "description": "Venue URL." }, "venue_capacity": { "type": [ "integer", "null" ], "description": "Venue capacity (number of attendees)." }, "city": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Chartmetric city ID." }, "name": { "type": [ "string", "null" ], "description": "City name." }, "province": { "type": [ "string", "null" ], "description": "State, province, or first-level administrative subdivision." } }, "description": "Event city. Null when the venue has no associated city." }, "code2": { "type": [ "string", "null" ], "description": "Event country (ISO 3166-1 alpha-2)." }, "low_price": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Lowest available ticket price (SeatGeek or Ticketmaster source)." }, "high_price": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Highest available ticket price." }, "price": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Average / representative ticket price." }, "price_trend": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "date": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Date of the price observation (ISO 8601)." }, "price": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Average price on this date." } } }, "description": "SeatGeek-only 28-day price trend series; empty array for other sources." }, "currency": { "type": [ "string", "null" ], "description": "Currency code for the price fields (e.g. `USD`)." }, "is_headliner": { "type": [ "boolean", "null" ], "description": "Whether the artist is a headliner for the event." } } } } }, "required": [ "obj" ], "additionalProperties": false }, "examples": { "default": { "value": { "obj": [ { "id": 8553348, "event_name": "Modest Mouse at Greek Theatre", "jambase_event_url": "https://www.jambase.com/venue/greek-theatre", "songkick_event_url": null, "seatgeek_event_url": null, "ticketmaster_event_url": null, "image_url": null, "type": "Concert", "start_date": "2024-07-28T00:00:00.000Z", "end_date": "2024-07-28T00:00:00.000Z", "venue_id": 1, "venue_name": "Greek Theatre", "venue_url": "https://thegreekberkeley.com/", "venue_capacity": 8500, "city": { "id": 6312, "name": "Berkeley", "province": "California" }, "code2": "US", "low_price": 45, "high_price": 250, "price": 120, "price_trend": [ { "date": "2024-07-01", "price": 115 } ], "currency": "USD", "is_headliner": true } ] } } } } } } } } }, "/api/artist/{id}/news": { "get": { "summary": "News", "tags": [ "Artist" ], "operationId": "listArtistNews", "description": "Recent artist milestones formatted as news items. Each row carries a `summaryTemplate` (with `:placeholder` tokens) plus `summaryData` (token values) and `metadata` (entity ids for deep-linking). Items are selected from the last 90 days with importance `stars >= ceil(weight/2)`. `subType` indicates the underlying event kind (`album`, `track`, `chart`, `playlist`, `artist`) — `summaryData`/`metadata` shapes vary accordingly (kept permissive).", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer", "minimum": 2, "maximum": 2147483647, "not": { "enum": [ 1 ] }, "description": "Chartmetric artist ID. Note: id=1 ('Various Artists') is rejected." }, "required": true, "description": "Chartmetric artist ID. Note: id=1 ('Various Artists') is rejected.", "examples": { "default": { "value": 2 } } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "maximum": 50, "description": "Maximum number of news items to return. Defaults to 10, max 50.", "default": 10 }, "required": false, "description": "Maximum number of news items to return. Defaults to 10, max 50." }, { "name": "weight", "in": "query", "schema": { "type": "integer", "maximum": 10, "description": "Minimum milestone weight (2 weights = 1 star; items with `stars >= ceil(weight/2)` are included). Defaults to 5, max 10.", "default": 5 }, "required": false, "description": "Minimum milestone weight (2 weights = 1 star; items with `stars >= ceil(weight/2)` are included). Defaults to 5, max 10." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "array", "items": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 2147483647 }, { "type": "string" } ], "nullable": true, "description": "News-item ID derived from the underlying milestone aggregate." }, "type": { "type": [ "string", "null" ], "description": "Top-level entity type, always `artist` for this endpoint." }, "subType": { "type": [ "string", "null" ], "description": "Underlying event kind — `artist`, `track`, `album`, `chart`, or `playlist`. Determines the shape of `summaryData` and `metadata`." }, "formattedDate": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Display-formatted date for the news item." }, "imageUrl": { "type": [ "string", "null" ], "description": "Image URL associated with the news item." }, "summaryTemplate": { "type": [ "string", "null" ], "description": "Summary string with `:placeholder` tokens to be filled from `summaryData`." }, "summaryData": { "type": [ "object", "null" ], "properties": { "chartName": { "type": [ "string", "null" ], "description": "Name of the chart (when `subType=chart`)." }, "playlistName": { "type": [ "string", "null" ], "description": "Name of the playlist (when `subType=playlist`)." }, "trackName": { "type": [ "string", "null" ], "description": "Name of the track (when `subType=track`)." }, "albumName": { "type": [ "string", "null" ], "description": "Name of the album (when `subType=album`)." } }, "description": "Token values for `summaryTemplate` placeholders. Populated keys vary by `subType`; additional ad-hoc tokens may appear." }, "metadata": { "type": [ "object", "null" ], "properties": { "playlist_id": { "type": [ "string", "null" ], "description": "Platform playlist ID (when `subType=playlist` or `chart`)." }, "playlistUrlParam": { "type": [ "string", "null" ], "description": "URL parameter for deep-linking to the playlist." }, "cmTrackId": { "type": [ "integer", "null" ], "description": "Chartmetric track ID (when `subType=track`)." }, "artistName": { "type": [ "string", "null" ], "description": "Artist display name." }, "cmArtistId": { "type": [ "integer", "null" ], "description": "Chartmetric artist ID (when `subType=artist`)." } }, "description": "Entity IDs for deep-linking. Populated keys vary by `subType`; additional metadata keys may appear." }, "stars": { "type": [ "integer", "null" ], "description": "Star rating (1-5) reflecting milestone importance." }, "group_size": { "anyOf": [ { "type": [ "integer", "null" ] }, { "type": "string" } ], "description": "Number of news items aggregated into this group when grouping is applied." } } } } }, "required": [ "obj" ], "additionalProperties": false }, "examples": { "default": { "value": { "obj": [ { "id": "1", "type": "artist", "subType": "playlist", "formattedDate": "2025-02-21", "imageUrl": "https://i.scdn.co/image/ab67616d0000b27317db30ce3f081d6818a8ad49", "summaryTemplate": ":trackName added to Spotify :playlistName at position 1 with 17.2K followers.", "summaryData": { "playlistName": "BAD NIGHTAN", "trackName": "Run BTS" }, "metadata": { "playlist_id": "16165930", "playlistUrlParam": "playlist/spotify?id=16165930", "cmTrackId": 83623672, "artistName": "BTS", "cmArtistId": 206557 }, "stars": 3 } ] } } } } } } } } }, "/api/artist/{id}/venues": { "get": { "summary": "Venues", "tags": [ "Artist" ], "operationId": "listArtistVenues", "description": "Venues where the artist has performed (past or scheduled), grouped by venue with the events that took place at each. Venues are sorted by capacity descending and paginated via `limit`/`offset`. Each venue row nests a narrow `events[]` subset — full event detail (pricing, images, status-annotated name) comes from `/api/artist/{id}/{status}/events`. Returns `[]` when the artist has no linked venues or events.", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer", "minimum": 2, "maximum": 2147483647, "not": { "enum": [ 1 ] }, "description": "Chartmetric artist ID. Note: id=1 ('Various Artists') is rejected." }, "required": true, "description": "Chartmetric artist ID. Note: id=1 ('Various Artists') is rejected.", "examples": { "default": { "value": 2 } } }, { "name": "limit", "in": "query", "schema": { "type": "number", "format": "float", "maximum": 100, "description": "Maximum number of venues to return. Defaults to 20, max 100.", "default": 20 }, "required": false, "description": "Maximum number of venues to return. Defaults to 20, max 100." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, "required": false, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "array", "items": { "type": "object", "properties": { "venue_id": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Chartmetric venue ID." }, "venue_name": { "type": [ "string", "null" ], "description": "Venue name." }, "venue_url": { "type": [ "string", "null" ], "description": "Venue URL." }, "venue_capacity": { "type": [ "integer", "null" ], "description": "Venue capacity (number of attendees)." }, "city": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Chartmetric city ID." }, "name": { "type": [ "string", "null" ], "description": "City name." } }, "description": "City of the venue. Null when the venue has no associated city." }, "code2": { "type": [ "string", "null" ], "description": "Venue country (ISO 3166-1 alpha-2)." }, "events": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Chartmetric event ID." }, "event_name": { "type": [ "string", "null" ], "description": "Event name." }, "jambase_event_url": { "type": [ "string", "null" ], "description": "JamBase URL for the event." }, "songkick_event_url": { "type": [ "string", "null" ], "description": "Songkick URL for the event." }, "seatgeek_event_url": { "type": [ "string", "null" ], "description": "SeatGeek URL for the event." }, "type": { "type": [ "string", "null" ], "description": "Event type (e.g. `Concert`, `Festival`)." }, "start_date": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Event start date (ISO 8601)." }, "end_date": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Event end date (ISO 8601)." }, "is_headliner": { "type": [ "boolean", "null" ], "description": "Whether the artist is a headliner for the event." } } }, "description": "Events the artist has performed at this venue." } } } } }, "required": [ "obj" ], "additionalProperties": false }, "examples": { "default": { "value": { "obj": [ { "venue_id": 434, "venue_name": "Dodger Stadium", "venue_url": "https://www.jambase.com/venue/dodger-stadium", "venue_capacity": 56000, "city": { "id": 7058, "name": "Los Angeles" }, "code2": "US", "events": [ { "id": 356, "event_name": "Besame Mucho (cancelled)", "jambase_event_url": "https://www.jambase.com/festival/besame-mucho-2024", "songkick_event_url": "https://www.songkick.com/festivals/2317029-besame-mucho/id/41963404-besame-mucho-2024", "seatgeek_event_url": null, "type": "Festival", "start_date": "2024-12-21T00:00:00.000Z", "end_date": "2024-12-21T00:00:00.000Z", "is_headliner": true } ] } ] } } } } } } } } }, "/api/artist/{id}/similar-artists/by-configurations": { "get": { "summary": "Similar Artists by Configurations", "tags": [ "Artist" ], "operationId": "listArtistSimilarArtistsByConfigurations", "description": "Similar artists ranked by weighted embedding configurations (`audience`, `mood`, `genre`, `musicality`). Query must include at least one configuration. Pass `segmentSize` to switch to a segmented shape (`by_stage` / `by_health`) instead of a flat list. `similarity` (up to 1) says how alike the artists are; for `audience`, how alike their audiences look, not how many fans they share. With one configuration, artists more similar than its weight are left out (`low` at 0.33, `medium` at 0.66, `high` at 1), so lower weights drop the closest artists and the target artist is usually missing. With two or more, the target comes first at 1.", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer", "minimum": 2, "maximum": 2147483647, "not": { "enum": [ 1 ] }, "description": "Chartmetric artist ID. Note: id=1 ('Various Artists') is rejected." }, "required": true, "description": "Chartmetric artist ID. Note: id=1 ('Various Artists') is rejected.", "examples": { "default": { "value": 2 } } }, { "name": "audience", "in": "query", "schema": { "type": "string", "enum": [ "low", "medium", "high" ], "description": "Weight of audience-similarity dimension. One of `low`, `medium`, `high`." }, "required": false, "description": "Weight of audience-similarity dimension. One of `low`, `medium`, `high`." }, { "name": "mood", "in": "query", "schema": { "type": "string", "enum": [ "low", "medium", "high" ], "description": "Weight of mood-similarity dimension. One of `low`, `medium`, `high`." }, "required": false, "description": "Weight of mood-similarity dimension. One of `low`, `medium`, `high`." }, { "name": "genre", "in": "query", "schema": { "type": "string", "enum": [ "low", "medium", "high" ], "description": "Weight of genre-similarity dimension. One of `low`, `medium`, `high`." }, "required": false, "description": "Weight of genre-similarity dimension. One of `low`, `medium`, `high`." }, { "name": "musicality", "in": "query", "schema": { "type": "string", "enum": [ "low", "medium", "high" ], "description": "Weight of musicality-similarity dimension. One of `low`, `medium`, `high`." }, "required": false, "description": "Weight of musicality-similarity dimension. One of `low`, `medium`, `high`." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "description": "Maximum number of similar artists to return. Defaults to 20.", "default": 20 }, "required": false, "description": "Maximum number of similar artists to return. Defaults to 20." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, "required": false, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "anyOf": [ { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Chartmetric artist ID." }, "name": { "type": [ "string", "null" ], "description": "Artist name." }, "image_url": { "type": [ "string", "null" ], "description": "Artist image URL." }, "code2": { "type": [ "string", "null" ], "description": "Artist country (ISO 3166-1 alpha-2)." }, "verified": { "type": [ "boolean", "null" ], "description": "True for Chartmetric-verified artists." }, "gender": { "type": [ "integer", "null" ], "description": "Internal gender code." }, "band": { "type": [ "boolean", "null" ], "description": "True when the profile represents a band." }, "genres": { "type": [ "array", "null" ], "items": {}, "description": "List of genre objects for the artist." }, "subgenres": { "type": [ "array", "null" ], "items": {}, "description": "List of sub-genre objects for the artist." }, "primary_genre_smart": { "anyOf": [ { "type": "object", "properties": {}, "description": "Genre `{ id, name }`." }, { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Artist's primary genre, resolved to either an object or a name/ID." }, "continent": { "type": [ "string", "null" ], "description": "Continent code derived from `code2`." }, "rank": { "type": [ "integer", "null" ], "description": "Chartmetric overall artist rank." }, "score": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Chartmetric artist score (0–100)." }, "similarity": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Weighted similarity to the target across the requested configurations, up to 1. How alike the artists are, not a share of shared fans." }, "career_stage": { "type": [ "string", "null" ], "description": "Artist's current career stage." }, "recent_momentum": { "type": [ "string", "null" ], "description": "Artist's recent momentum category." }, "network_strength": { "type": [ "string", "null" ], "description": "Artist's network-strength category (`active`, `emerging`, `established`, `prominent`, `influential`)." }, "label": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 2147483647 }, { "type": "string" }, { "type": "object", "properties": {}, "description": "Label `{ id, name }`." } ], "nullable": true, "description": "Artist's record label (resolved object, name, or ID)." }, "rank_stats_monthly": { "type": [ "array", "null" ], "items": {}, "description": "Monthly rank-stats time series for the artist." }, "rank_diff_monthly": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Monthly change in `rank`." }, "date_of_birth": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Date of birth (ISO 8601), when known." }, "normalizedScores": { "type": "object", "properties": {}, "description": "Per-dimension normalized similarity scores for this row, when `mainArtistNormalizedScores` is computed." }, "dimensionScores": { "type": "object", "properties": { "mood": { "type": [ "number", "null" ], "format": "float", "description": "Cosine similarity for the mood dimension (0–1)." }, "genre": { "type": [ "number", "null" ], "format": "float", "description": "Cosine similarity for the genre dimension (0–1)." }, "audience": { "type": [ "number", "null" ], "format": "float", "description": "Cosine similarity for the audience dimension (0–1)." }, "musicality": { "type": [ "number", "null" ], "format": "float", "description": "Cosine similarity for the musicality dimension (0–1)." } }, "description": "Independent per-dimension cosine similarity scores (audience/mood/genre/musicality). Each is computed from the main artist vs. compared artist PCA vectors and is unweighted, so it reflects raw similarity in that dimension regardless of the requested `configurations` weights." } } }, "description": "Similar artists, best first; the target leads when it scores highest." }, "total": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Total number of similar artists matching the configurations." }, "mainArtistNormalizedScores": { "type": "object", "properties": {}, "description": "Per-dimension normalized similarity scores for the target artist." } } }, { "type": "object", "properties": { "by_stage": { "type": "object", "properties": {}, "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Chartmetric artist ID." }, "name": { "type": [ "string", "null" ], "description": "Artist name." }, "image_url": { "type": [ "string", "null" ], "description": "Artist image URL." }, "code2": { "type": [ "string", "null" ], "description": "Artist country (ISO 3166-1 alpha-2)." }, "verified": { "type": [ "boolean", "null" ], "description": "True for Chartmetric-verified artists." }, "gender": { "type": [ "integer", "null" ], "description": "Internal gender code." }, "band": { "type": [ "boolean", "null" ], "description": "True when the profile represents a band." }, "genres": { "type": [ "array", "null" ], "items": {}, "description": "List of genre objects for the artist." }, "subgenres": { "type": [ "array", "null" ], "items": {}, "description": "List of sub-genre objects for the artist." }, "primary_genre_smart": { "anyOf": [ { "type": "object", "properties": {}, "description": "Genre `{ id, name }`." }, { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Artist's primary genre, resolved to either an object or a name/ID." }, "continent": { "type": [ "string", "null" ], "description": "Continent code derived from `code2`." }, "rank": { "type": [ "integer", "null" ], "description": "Chartmetric overall artist rank." }, "score": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Chartmetric artist score (0–100)." }, "similarity": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Weighted similarity to the target across the requested configurations, up to 1. How alike the artists are, not a share of shared fans." }, "career_stage": { "type": [ "string", "null" ], "description": "Artist's current career stage." }, "recent_momentum": { "type": [ "string", "null" ], "description": "Artist's recent momentum category." }, "network_strength": { "type": [ "string", "null" ], "description": "Artist's network-strength category (`active`, `emerging`, `established`, `prominent`, `influential`)." }, "label": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 2147483647 }, { "type": "string" }, { "type": "object", "properties": {}, "description": "Label `{ id, name }`." } ], "nullable": true, "description": "Artist's record label (resolved object, name, or ID)." }, "rank_stats_monthly": { "type": [ "array", "null" ], "items": {}, "description": "Monthly rank-stats time series for the artist." }, "rank_diff_monthly": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Monthly change in `rank`." }, "date_of_birth": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Date of birth (ISO 8601), when known." }, "normalizedScores": { "type": "object", "properties": {}, "description": "Per-dimension normalized similarity scores for this row, when `mainArtistNormalizedScores` is computed." }, "dimensionScores": { "type": "object", "properties": { "mood": { "type": [ "number", "null" ], "format": "float", "description": "Cosine similarity for the mood dimension (0–1)." }, "genre": { "type": [ "number", "null" ], "format": "float", "description": "Cosine similarity for the genre dimension (0–1)." }, "audience": { "type": [ "number", "null" ], "format": "float", "description": "Cosine similarity for the audience dimension (0–1)." }, "musicality": { "type": [ "number", "null" ], "format": "float", "description": "Cosine similarity for the musicality dimension (0–1)." } }, "description": "Independent per-dimension cosine similarity scores (audience/mood/genre/musicality). Each is computed from the main artist vs. compared artist PCA vectors and is unweighted, so it reflects raw similarity in that dimension regardless of the requested `configurations` weights." } } } }, "description": "Map of career-stage bucket → list of similar artists in that stage." }, "by_health": { "type": "object", "properties": {}, "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Chartmetric artist ID." }, "name": { "type": [ "string", "null" ], "description": "Artist name." }, "image_url": { "type": [ "string", "null" ], "description": "Artist image URL." }, "code2": { "type": [ "string", "null" ], "description": "Artist country (ISO 3166-1 alpha-2)." }, "verified": { "type": [ "boolean", "null" ], "description": "True for Chartmetric-verified artists." }, "gender": { "type": [ "integer", "null" ], "description": "Internal gender code." }, "band": { "type": [ "boolean", "null" ], "description": "True when the profile represents a band." }, "genres": { "type": [ "array", "null" ], "items": {}, "description": "List of genre objects for the artist." }, "subgenres": { "type": [ "array", "null" ], "items": {}, "description": "List of sub-genre objects for the artist." }, "primary_genre_smart": { "anyOf": [ { "type": "object", "properties": {}, "description": "Genre `{ id, name }`." }, { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Artist's primary genre, resolved to either an object or a name/ID." }, "continent": { "type": [ "string", "null" ], "description": "Continent code derived from `code2`." }, "rank": { "type": [ "integer", "null" ], "description": "Chartmetric overall artist rank." }, "score": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Chartmetric artist score (0–100)." }, "similarity": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Weighted similarity to the target across the requested configurations, up to 1. How alike the artists are, not a share of shared fans." }, "career_stage": { "type": [ "string", "null" ], "description": "Artist's current career stage." }, "recent_momentum": { "type": [ "string", "null" ], "description": "Artist's recent momentum category." }, "network_strength": { "type": [ "string", "null" ], "description": "Artist's network-strength category (`active`, `emerging`, `established`, `prominent`, `influential`)." }, "label": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 2147483647 }, { "type": "string" }, { "type": "object", "properties": {}, "description": "Label `{ id, name }`." } ], "nullable": true, "description": "Artist's record label (resolved object, name, or ID)." }, "rank_stats_monthly": { "type": [ "array", "null" ], "items": {}, "description": "Monthly rank-stats time series for the artist." }, "rank_diff_monthly": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Monthly change in `rank`." }, "date_of_birth": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Date of birth (ISO 8601), when known." }, "normalizedScores": { "type": "object", "properties": {}, "description": "Per-dimension normalized similarity scores for this row, when `mainArtistNormalizedScores` is computed." }, "dimensionScores": { "type": "object", "properties": { "mood": { "type": [ "number", "null" ], "format": "float", "description": "Cosine similarity for the mood dimension (0–1)." }, "genre": { "type": [ "number", "null" ], "format": "float", "description": "Cosine similarity for the genre dimension (0–1)." }, "audience": { "type": [ "number", "null" ], "format": "float", "description": "Cosine similarity for the audience dimension (0–1)." }, "musicality": { "type": [ "number", "null" ], "format": "float", "description": "Cosine similarity for the musicality dimension (0–1)." } }, "description": "Independent per-dimension cosine similarity scores (audience/mood/genre/musicality). Each is computed from the main artist vs. compared artist PCA vectors and is unweighted, so it reflects raw similarity in that dimension regardless of the requested `configurations` weights." } } } }, "description": "Map of career-health bucket → list of similar artists in that bucket." } } } ] } }, "additionalProperties": false }, "examples": { "default": { "value": { "obj": { "data": [ { "id": 213758, "name": "Ashe", "image_url": "https://i.scdn.co/image/ab6761610000e5eb91054f6fce16973e80f0ed2a", "code2": "US", "verified": false, "gender": 0, "band": false, "genres": [ { "id": 501160, "name": "pop" } ], "subgenres": [ { "id": 419163, "name": "indie pop" } ], "primary_genre_smart": { "id": 501160, "name": "pop" }, "rank": 2657, "score": 88.61378455109873, "similarity": 0.8710287, "career_stage": "mainstream", "recent_momentum": "steady", "network_strength": "prominent", "label": { "id": 1038765, "name": "Mom + Pop Music" }, "rank_stats_monthly": [], "rank_diff_monthly": 0, "date_of_birth": "1993-05-07" } ], "total": 10000 } } } } } } } } } }, "/api/artist/{id}/cmStats": { "get": { "summary": "Artist Cached Stats & Trends", "tags": [ "Artist" ], "operationId": "getArtistCmStats", "description": "Cached artist stats snapshot with latest values plus weekly / monthly / bimonthly diffs and diff-percents. `latest` combines platform metrics (followers, listeners, playlist reach, ...) with rank fields (`sp_popularity_rank`, `fan_base_rank`, ...). `weekly_diff`, `monthly_diff`, and `bimonthly_diff` buckets carry only the platform metrics (no ranks). Field names are drawn from `CONSTANTS.ARTIST.CM_STATS.PLATFORM` / `.RANK`; the map is sparse (only populated for platforms where the artist has data). All values are `number | null`.", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer", "minimum": 2, "maximum": 2147483647, "not": { "enum": [ 1 ] }, "description": "Chartmetric artist ID. Note: id=1 ('Various Artists') is rejected." }, "required": true, "description": "Chartmetric artist ID. Note: id=1 ('Various Artists') is rejected.", "examples": { "default": { "value": 2 } } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "object", "properties": { "timestamp": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Snapshot timestamp (ISO 8601)." }, "latest": { "type": [ "object", "null" ], "properties": { "sp_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Spotify follower count." }, "sp_monthly_listeners": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Spotify monthly listener count." }, "sp_popularity": { "type": [ "number", "null" ], "format": "float", "description": "Spotify popularity score (0–100)." }, "sp_listeners_to_followers_ratio": { "type": [ "number", "null" ], "format": "float", "description": "Ratio of Spotify monthly listeners to Spotify followers." }, "sp_followers_to_listeners_ratio": { "type": [ "number", "null" ], "format": "float", "description": "Ratio of Spotify followers to Spotify monthly listeners." }, "deezer_fans": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Deezer fan count." }, "fs_likes": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Facebook page-like count." }, "fs_talks": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Facebook people-talking-about count: users discussing or interacting with the page." }, "ins_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Instagram follower count." }, "ts_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Twitter/X follower count." }, "ts_retweets": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Twitter/X retweet count." }, "ycs_views": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "YouTube channel total view count." }, "ycs_subscribers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "YouTube channel subscriber count." }, "youtube_daily_video_views": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "YouTube daily video view count." }, "youtube_monthly_video_views": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "YouTube monthly video view count." }, "ws_views": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Wikipedia page-view count." }, "soundcloud_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "SoundCloud follower count." }, "bs_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Bandsintown follower count." }, "tiktok_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "TikTok follower count." }, "tiktok_likes": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "TikTok total like count." }, "cm_artist_rank": { "type": [ "number", "null" ], "format": "float", "description": "Global Chartmetric artist rank (1 is highest)." }, "sp_followers_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Spotify followers." }, "sp_popularity_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Spotify popularity." }, "sp_monthly_listeners_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Spotify monthly listeners." }, "sp_where_people_listen": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "code2": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-2 country code of the listener location." }, "listeners": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Spotify monthly listener count for this location. May arrive as string (uncast aggregate)." }, "name": { "type": [ "string", "null" ], "description": "City or country name of the listener location." } } }, "description": "Top Spotify listener locations (countries/cities)." }, "deezer_fans_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Deezer fans." }, "ins_followers_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Instagram followers." }, "ycs_subscribers_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by YouTube channel subscribers." }, "ycs_views_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by YouTube channel views." }, "tiktok_followers_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by TikTok followers." }, "tiktok_likes_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by TikTok likes." }, "tiktok_top_video_views": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Top TikTok video view count." }, "tiktok_top_video_views_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by top TikTok video views." }, "tiktok_top_video_comments": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Top TikTok video comment count." }, "tiktok_top_video_comments_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by top TikTok video comments." }, "tiktok_track_posts": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Total TikTok posts using the artist’s tracks." }, "tiktok_track_posts_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by TikTok track posts." }, "twitter_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Twitter follower count." }, "twitter_followers_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Twitter followers." }, "line_music_artist_likes": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Line Music artist like count." }, "line_music_artist_likes_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Line Music artist likes." }, "line_music_likes": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Line Music track-likes total." }, "line_music_likes_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Line Music likes." }, "line_music_plays": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Line Music play count." }, "line_music_plays_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Line Music plays." }, "line_music_mv_plays": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Line Music music-video play count." }, "fan_base_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric fan-base composite rank." }, "engagement_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric engagement composite rank." }, "youtube_daily_video_views_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by YouTube daily video views." }, "youtube_monthly_video_views_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by YouTube monthly video views." }, "twitch_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Twitch follower count." }, "twitch_followers_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Twitch followers." }, "twitch_views": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Twitch total view count." }, "twitch_views_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Twitch views." }, "twitch_monthly_viewer_hours": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Twitch monthly viewer-hours." }, "twitch_monthly_viewer_hours_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Twitch monthly viewer-hours." }, "twitch_weekly_viewer_hours": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Twitch weekly viewer-hours." }, "twitch_weekly_viewer_hours_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Twitch weekly viewer-hours." }, "pandora_listeners_28_day": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Pandora 28-day listener count." }, "pandora_listeners_28_day_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Pandora 28-day listeners." }, "pandora_lifetime_stations_added": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Pandora lifetime stations-added count." }, "pandora_lifetime_stations_added_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Pandora lifetime stations added." }, "pandora_lifetime_streams": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Pandora lifetime stream count." }, "pandora_lifetime_streams_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Pandora lifetime streams." }, "boomplay_ranking_current": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Current Boomplay ranking." }, "boomplay_ranking_current_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by current Boomplay ranking." }, "boomplay_favorites": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Boomplay favorite count." }, "boomplay_favorites_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Boomplay favorites." }, "boomplay_shares": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Boomplay share count." }, "boomplay_shares_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Boomplay shares." }, "boomplay_comments": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Boomplay comment count." }, "boomplay_comments_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Boomplay comments." }, "boomplay_plays": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Boomplay play count." }, "boomplay_plays_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Boomplay plays." }, "num_sp_editorial_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of Spotify editorial playlists featuring this artist." }, "num_sp_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of Spotify playlists featuring this artist." }, "sp_playlist_total_reach": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Sum of followers from all Spotify playlists featuring this artist." }, "sp_editorial_playlist_total_reach": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Sum of followers from all Spotify editorial playlists featuring this artist." }, "num_am_editorial_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of Apple Music editorial playlists featuring this artist." }, "num_am_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of Apple Music playlists featuring this artist." }, "num_de_editorial_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of Deezer editorial playlists featuring this artist." }, "num_de_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of Deezer playlists featuring this artist." }, "de_playlist_total_reach": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Sum of fans from all Deezer playlists featuring this artist." }, "de_editorial_playlist_total_reach": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Sum of fans from all Deezer editorial playlists featuring this artist." }, "num_az_editorial_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of Amazon editorial playlists featuring this artist." }, "num_az_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of Amazon playlists featuring this artist." }, "num_yt_editorial_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of YouTube editorial playlists featuring this artist." }, "num_yt_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of YouTube playlists featuring this artist." }, "yt_playlist_total_reach": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Sum of views from all YouTube playlists featuring this artist." }, "yt_editorial_playlist_total_reach": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Sum of views from all YouTube editorial playlists featuring this artist." }, "shazam_count": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Sum of Shazam plays across the artist's tracks." }, "genius_pageviews": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Total Genius page-view count for the artist." }, "genreRank": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ], "description": "Name of the top genre." }, "rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank within the top genre." } } }, "subGenreRank1": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ], "description": "Name of the first top sub-genre." }, "rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank within the first top sub-genre." } } }, "subGenreRank2": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ], "description": "Name of the second top sub-genre." }, "rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank within the second top sub-genre." } } }, "countryRank": { "type": [ "object", "null" ], "properties": { "country": { "type": [ "string", "null" ], "description": "Country name." }, "rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank within the country." } }, "description": "Artist's rank within their primary country." } }, "description": "Latest values for platform metrics plus rank fields (e.g. `sp_popularity_rank`)." }, "weekly_diff": { "type": [ "object", "null" ], "properties": { "sp_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Spotify follower count." }, "sp_monthly_listeners": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Spotify monthly listener count." }, "sp_popularity": { "type": [ "number", "null" ], "format": "float", "description": "Spotify popularity score (0–100)." }, "sp_listeners_to_followers_ratio": { "type": [ "number", "null" ], "format": "float", "description": "Ratio of Spotify monthly listeners to Spotify followers." }, "sp_followers_to_listeners_ratio": { "type": [ "number", "null" ], "format": "float", "description": "Ratio of Spotify followers to Spotify monthly listeners." }, "deezer_fans": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Deezer fan count." }, "fs_likes": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Facebook page-like count." }, "fs_talks": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Facebook people-talking-about count: users discussing or interacting with the page." }, "ins_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Instagram follower count." }, "ts_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Twitter/X follower count." }, "ts_retweets": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Twitter/X retweet count." }, "ycs_views": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "YouTube channel total view count." }, "ycs_subscribers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "YouTube channel subscriber count." }, "youtube_daily_video_views": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "YouTube daily video view count." }, "youtube_monthly_video_views": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "YouTube monthly video view count." }, "ws_views": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Wikipedia page-view count." }, "soundcloud_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "SoundCloud follower count." }, "bs_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Bandsintown follower count." }, "tiktok_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "TikTok follower count." }, "tiktok_likes": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "TikTok total like count." }, "cm_artist_rank": { "type": [ "number", "null" ], "format": "float", "description": "Global Chartmetric artist rank (1 is highest)." }, "sp_followers_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Spotify followers." }, "sp_popularity_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Spotify popularity." }, "sp_monthly_listeners_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Spotify monthly listeners." }, "sp_where_people_listen": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "code2": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-2 country code of the listener location." }, "listeners": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Spotify monthly listener count for this location. May arrive as string (uncast aggregate)." }, "name": { "type": [ "string", "null" ], "description": "City or country name of the listener location." } } }, "description": "Top Spotify listener locations (countries/cities)." }, "deezer_fans_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Deezer fans." }, "ins_followers_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Instagram followers." }, "ycs_subscribers_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by YouTube channel subscribers." }, "ycs_views_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by YouTube channel views." }, "tiktok_followers_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by TikTok followers." }, "tiktok_likes_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by TikTok likes." }, "tiktok_top_video_views": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Top TikTok video view count." }, "tiktok_top_video_views_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by top TikTok video views." }, "tiktok_top_video_comments": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Top TikTok video comment count." }, "tiktok_top_video_comments_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by top TikTok video comments." }, "tiktok_track_posts": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Total TikTok posts using the artist’s tracks." }, "tiktok_track_posts_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by TikTok track posts." }, "twitter_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Twitter follower count." }, "twitter_followers_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Twitter followers." }, "line_music_artist_likes": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Line Music artist like count." }, "line_music_artist_likes_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Line Music artist likes." }, "line_music_likes": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Line Music track-likes total." }, "line_music_likes_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Line Music likes." }, "line_music_plays": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Line Music play count." }, "line_music_plays_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Line Music plays." }, "line_music_mv_plays": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Line Music music-video play count." }, "fan_base_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric fan-base composite rank." }, "engagement_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric engagement composite rank." }, "youtube_daily_video_views_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by YouTube daily video views." }, "youtube_monthly_video_views_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by YouTube monthly video views." }, "twitch_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Twitch follower count." }, "twitch_followers_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Twitch followers." }, "twitch_views": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Twitch total view count." }, "twitch_views_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Twitch views." }, "twitch_monthly_viewer_hours": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Twitch monthly viewer-hours." }, "twitch_monthly_viewer_hours_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Twitch monthly viewer-hours." }, "twitch_weekly_viewer_hours": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Twitch weekly viewer-hours." }, "twitch_weekly_viewer_hours_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Twitch weekly viewer-hours." }, "pandora_listeners_28_day": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Pandora 28-day listener count." }, "pandora_listeners_28_day_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Pandora 28-day listeners." }, "pandora_lifetime_stations_added": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Pandora lifetime stations-added count." }, "pandora_lifetime_stations_added_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Pandora lifetime stations added." }, "pandora_lifetime_streams": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Pandora lifetime stream count." }, "pandora_lifetime_streams_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Pandora lifetime streams." }, "boomplay_ranking_current": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Current Boomplay ranking." }, "boomplay_ranking_current_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by current Boomplay ranking." }, "boomplay_favorites": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Boomplay favorite count." }, "boomplay_favorites_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Boomplay favorites." }, "boomplay_shares": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Boomplay share count." }, "boomplay_shares_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Boomplay shares." }, "boomplay_comments": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Boomplay comment count." }, "boomplay_comments_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Boomplay comments." }, "boomplay_plays": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Boomplay play count." }, "boomplay_plays_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Boomplay plays." }, "num_sp_editorial_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of Spotify editorial playlists featuring this artist." }, "num_sp_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of Spotify playlists featuring this artist." }, "sp_playlist_total_reach": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Sum of followers from all Spotify playlists featuring this artist." }, "sp_editorial_playlist_total_reach": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Sum of followers from all Spotify editorial playlists featuring this artist." }, "num_am_editorial_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of Apple Music editorial playlists featuring this artist." }, "num_am_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of Apple Music playlists featuring this artist." }, "num_de_editorial_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of Deezer editorial playlists featuring this artist." }, "num_de_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of Deezer playlists featuring this artist." }, "de_playlist_total_reach": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Sum of fans from all Deezer playlists featuring this artist." }, "de_editorial_playlist_total_reach": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Sum of fans from all Deezer editorial playlists featuring this artist." }, "num_az_editorial_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of Amazon editorial playlists featuring this artist." }, "num_az_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of Amazon playlists featuring this artist." }, "num_yt_editorial_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of YouTube editorial playlists featuring this artist." }, "num_yt_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of YouTube playlists featuring this artist." }, "yt_playlist_total_reach": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Sum of views from all YouTube playlists featuring this artist." }, "yt_editorial_playlist_total_reach": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Sum of views from all YouTube editorial playlists featuring this artist." }, "shazam_count": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Sum of Shazam plays across the artist's tracks." }, "genius_pageviews": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Total Genius page-view count for the artist." }, "genreRank": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ], "description": "Name of the top genre." }, "rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank within the top genre." } } }, "subGenreRank1": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ], "description": "Name of the first top sub-genre." }, "rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank within the first top sub-genre." } } }, "subGenreRank2": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ], "description": "Name of the second top sub-genre." }, "rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank within the second top sub-genre." } } }, "countryRank": { "type": [ "object", "null" ], "properties": { "country": { "type": [ "string", "null" ], "description": "Country name." }, "rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank within the country." } }, "description": "Artist's rank within their primary country." } }, "description": "Absolute change in platform metrics versus 7 days ago. Ranks not included." }, "weekly_diff_percent": { "type": [ "object", "null" ], "properties": { "sp_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Spotify follower count." }, "sp_monthly_listeners": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Spotify monthly listener count." }, "sp_popularity": { "type": [ "number", "null" ], "format": "float", "description": "Spotify popularity score (0–100)." }, "sp_listeners_to_followers_ratio": { "type": [ "number", "null" ], "format": "float", "description": "Ratio of Spotify monthly listeners to Spotify followers." }, "sp_followers_to_listeners_ratio": { "type": [ "number", "null" ], "format": "float", "description": "Ratio of Spotify followers to Spotify monthly listeners." }, "deezer_fans": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Deezer fan count." }, "fs_likes": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Facebook page-like count." }, "fs_talks": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Facebook people-talking-about count: users discussing or interacting with the page." }, "ins_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Instagram follower count." }, "ts_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Twitter/X follower count." }, "ts_retweets": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Twitter/X retweet count." }, "ycs_views": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "YouTube channel total view count." }, "ycs_subscribers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "YouTube channel subscriber count." }, "youtube_daily_video_views": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "YouTube daily video view count." }, "youtube_monthly_video_views": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "YouTube monthly video view count." }, "ws_views": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Wikipedia page-view count." }, "soundcloud_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "SoundCloud follower count." }, "bs_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Bandsintown follower count." }, "tiktok_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "TikTok follower count." }, "tiktok_likes": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "TikTok total like count." }, "cm_artist_rank": { "type": [ "number", "null" ], "format": "float", "description": "Global Chartmetric artist rank (1 is highest)." }, "sp_followers_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Spotify followers." }, "sp_popularity_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Spotify popularity." }, "sp_monthly_listeners_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Spotify monthly listeners." }, "sp_where_people_listen": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "code2": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-2 country code of the listener location." }, "listeners": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Spotify monthly listener count for this location. May arrive as string (uncast aggregate)." }, "name": { "type": [ "string", "null" ], "description": "City or country name of the listener location." } } }, "description": "Top Spotify listener locations (countries/cities)." }, "deezer_fans_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Deezer fans." }, "ins_followers_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Instagram followers." }, "ycs_subscribers_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by YouTube channel subscribers." }, "ycs_views_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by YouTube channel views." }, "tiktok_followers_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by TikTok followers." }, "tiktok_likes_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by TikTok likes." }, "tiktok_top_video_views": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Top TikTok video view count." }, "tiktok_top_video_views_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by top TikTok video views." }, "tiktok_top_video_comments": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Top TikTok video comment count." }, "tiktok_top_video_comments_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by top TikTok video comments." }, "tiktok_track_posts": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Total TikTok posts using the artist’s tracks." }, "tiktok_track_posts_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by TikTok track posts." }, "twitter_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Twitter follower count." }, "twitter_followers_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Twitter followers." }, "line_music_artist_likes": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Line Music artist like count." }, "line_music_artist_likes_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Line Music artist likes." }, "line_music_likes": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Line Music track-likes total." }, "line_music_likes_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Line Music likes." }, "line_music_plays": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Line Music play count." }, "line_music_plays_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Line Music plays." }, "line_music_mv_plays": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Line Music music-video play count." }, "fan_base_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric fan-base composite rank." }, "engagement_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric engagement composite rank." }, "youtube_daily_video_views_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by YouTube daily video views." }, "youtube_monthly_video_views_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by YouTube monthly video views." }, "twitch_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Twitch follower count." }, "twitch_followers_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Twitch followers." }, "twitch_views": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Twitch total view count." }, "twitch_views_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Twitch views." }, "twitch_monthly_viewer_hours": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Twitch monthly viewer-hours." }, "twitch_monthly_viewer_hours_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Twitch monthly viewer-hours." }, "twitch_weekly_viewer_hours": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Twitch weekly viewer-hours." }, "twitch_weekly_viewer_hours_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Twitch weekly viewer-hours." }, "pandora_listeners_28_day": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Pandora 28-day listener count." }, "pandora_listeners_28_day_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Pandora 28-day listeners." }, "pandora_lifetime_stations_added": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Pandora lifetime stations-added count." }, "pandora_lifetime_stations_added_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Pandora lifetime stations added." }, "pandora_lifetime_streams": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Pandora lifetime stream count." }, "pandora_lifetime_streams_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Pandora lifetime streams." }, "boomplay_ranking_current": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Current Boomplay ranking." }, "boomplay_ranking_current_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by current Boomplay ranking." }, "boomplay_favorites": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Boomplay favorite count." }, "boomplay_favorites_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Boomplay favorites." }, "boomplay_shares": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Boomplay share count." }, "boomplay_shares_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Boomplay shares." }, "boomplay_comments": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Boomplay comment count." }, "boomplay_comments_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Boomplay comments." }, "boomplay_plays": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Boomplay play count." }, "boomplay_plays_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Boomplay plays." }, "num_sp_editorial_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of Spotify editorial playlists featuring this artist." }, "num_sp_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of Spotify playlists featuring this artist." }, "sp_playlist_total_reach": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Sum of followers from all Spotify playlists featuring this artist." }, "sp_editorial_playlist_total_reach": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Sum of followers from all Spotify editorial playlists featuring this artist." }, "num_am_editorial_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of Apple Music editorial playlists featuring this artist." }, "num_am_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of Apple Music playlists featuring this artist." }, "num_de_editorial_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of Deezer editorial playlists featuring this artist." }, "num_de_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of Deezer playlists featuring this artist." }, "de_playlist_total_reach": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Sum of fans from all Deezer playlists featuring this artist." }, "de_editorial_playlist_total_reach": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Sum of fans from all Deezer editorial playlists featuring this artist." }, "num_az_editorial_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of Amazon editorial playlists featuring this artist." }, "num_az_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of Amazon playlists featuring this artist." }, "num_yt_editorial_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of YouTube editorial playlists featuring this artist." }, "num_yt_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of YouTube playlists featuring this artist." }, "yt_playlist_total_reach": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Sum of views from all YouTube playlists featuring this artist." }, "yt_editorial_playlist_total_reach": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Sum of views from all YouTube editorial playlists featuring this artist." }, "shazam_count": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Sum of Shazam plays across the artist's tracks." }, "genius_pageviews": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Total Genius page-view count for the artist." }, "genreRank": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ], "description": "Name of the top genre." }, "rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank within the top genre." } } }, "subGenreRank1": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ], "description": "Name of the first top sub-genre." }, "rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank within the first top sub-genre." } } }, "subGenreRank2": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ], "description": "Name of the second top sub-genre." }, "rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank within the second top sub-genre." } } }, "countryRank": { "type": [ "object", "null" ], "properties": { "country": { "type": [ "string", "null" ], "description": "Country name." }, "rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank within the country." } }, "description": "Artist's rank within their primary country." } }, "description": "Percentage change in platform metrics versus 7 days ago." }, "monthly_diff": { "type": [ "object", "null" ], "properties": { "sp_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Spotify follower count." }, "sp_monthly_listeners": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Spotify monthly listener count." }, "sp_popularity": { "type": [ "number", "null" ], "format": "float", "description": "Spotify popularity score (0–100)." }, "sp_listeners_to_followers_ratio": { "type": [ "number", "null" ], "format": "float", "description": "Ratio of Spotify monthly listeners to Spotify followers." }, "sp_followers_to_listeners_ratio": { "type": [ "number", "null" ], "format": "float", "description": "Ratio of Spotify followers to Spotify monthly listeners." }, "deezer_fans": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Deezer fan count." }, "fs_likes": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Facebook page-like count." }, "fs_talks": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Facebook people-talking-about count: users discussing or interacting with the page." }, "ins_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Instagram follower count." }, "ts_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Twitter/X follower count." }, "ts_retweets": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Twitter/X retweet count." }, "ycs_views": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "YouTube channel total view count." }, "ycs_subscribers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "YouTube channel subscriber count." }, "youtube_daily_video_views": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "YouTube daily video view count." }, "youtube_monthly_video_views": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "YouTube monthly video view count." }, "ws_views": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Wikipedia page-view count." }, "soundcloud_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "SoundCloud follower count." }, "bs_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Bandsintown follower count." }, "tiktok_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "TikTok follower count." }, "tiktok_likes": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "TikTok total like count." }, "cm_artist_rank": { "type": [ "number", "null" ], "format": "float", "description": "Global Chartmetric artist rank (1 is highest)." }, "sp_followers_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Spotify followers." }, "sp_popularity_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Spotify popularity." }, "sp_monthly_listeners_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Spotify monthly listeners." }, "sp_where_people_listen": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "code2": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-2 country code of the listener location." }, "listeners": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Spotify monthly listener count for this location. May arrive as string (uncast aggregate)." }, "name": { "type": [ "string", "null" ], "description": "City or country name of the listener location." } } }, "description": "Top Spotify listener locations (countries/cities)." }, "deezer_fans_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Deezer fans." }, "ins_followers_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Instagram followers." }, "ycs_subscribers_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by YouTube channel subscribers." }, "ycs_views_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by YouTube channel views." }, "tiktok_followers_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by TikTok followers." }, "tiktok_likes_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by TikTok likes." }, "tiktok_top_video_views": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Top TikTok video view count." }, "tiktok_top_video_views_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by top TikTok video views." }, "tiktok_top_video_comments": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Top TikTok video comment count." }, "tiktok_top_video_comments_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by top TikTok video comments." }, "tiktok_track_posts": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Total TikTok posts using the artist’s tracks." }, "tiktok_track_posts_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by TikTok track posts." }, "twitter_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Twitter follower count." }, "twitter_followers_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Twitter followers." }, "line_music_artist_likes": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Line Music artist like count." }, "line_music_artist_likes_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Line Music artist likes." }, "line_music_likes": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Line Music track-likes total." }, "line_music_likes_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Line Music likes." }, "line_music_plays": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Line Music play count." }, "line_music_plays_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Line Music plays." }, "line_music_mv_plays": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Line Music music-video play count." }, "fan_base_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric fan-base composite rank." }, "engagement_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric engagement composite rank." }, "youtube_daily_video_views_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by YouTube daily video views." }, "youtube_monthly_video_views_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by YouTube monthly video views." }, "twitch_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Twitch follower count." }, "twitch_followers_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Twitch followers." }, "twitch_views": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Twitch total view count." }, "twitch_views_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Twitch views." }, "twitch_monthly_viewer_hours": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Twitch monthly viewer-hours." }, "twitch_monthly_viewer_hours_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Twitch monthly viewer-hours." }, "twitch_weekly_viewer_hours": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Twitch weekly viewer-hours." }, "twitch_weekly_viewer_hours_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Twitch weekly viewer-hours." }, "pandora_listeners_28_day": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Pandora 28-day listener count." }, "pandora_listeners_28_day_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Pandora 28-day listeners." }, "pandora_lifetime_stations_added": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Pandora lifetime stations-added count." }, "pandora_lifetime_stations_added_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Pandora lifetime stations added." }, "pandora_lifetime_streams": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Pandora lifetime stream count." }, "pandora_lifetime_streams_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Pandora lifetime streams." }, "boomplay_ranking_current": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Current Boomplay ranking." }, "boomplay_ranking_current_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by current Boomplay ranking." }, "boomplay_favorites": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Boomplay favorite count." }, "boomplay_favorites_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Boomplay favorites." }, "boomplay_shares": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Boomplay share count." }, "boomplay_shares_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Boomplay shares." }, "boomplay_comments": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Boomplay comment count." }, "boomplay_comments_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Boomplay comments." }, "boomplay_plays": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Boomplay play count." }, "boomplay_plays_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Boomplay plays." }, "num_sp_editorial_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of Spotify editorial playlists featuring this artist." }, "num_sp_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of Spotify playlists featuring this artist." }, "sp_playlist_total_reach": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Sum of followers from all Spotify playlists featuring this artist." }, "sp_editorial_playlist_total_reach": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Sum of followers from all Spotify editorial playlists featuring this artist." }, "num_am_editorial_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of Apple Music editorial playlists featuring this artist." }, "num_am_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of Apple Music playlists featuring this artist." }, "num_de_editorial_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of Deezer editorial playlists featuring this artist." }, "num_de_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of Deezer playlists featuring this artist." }, "de_playlist_total_reach": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Sum of fans from all Deezer playlists featuring this artist." }, "de_editorial_playlist_total_reach": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Sum of fans from all Deezer editorial playlists featuring this artist." }, "num_az_editorial_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of Amazon editorial playlists featuring this artist." }, "num_az_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of Amazon playlists featuring this artist." }, "num_yt_editorial_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of YouTube editorial playlists featuring this artist." }, "num_yt_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of YouTube playlists featuring this artist." }, "yt_playlist_total_reach": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Sum of views from all YouTube playlists featuring this artist." }, "yt_editorial_playlist_total_reach": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Sum of views from all YouTube editorial playlists featuring this artist." }, "shazam_count": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Sum of Shazam plays across the artist's tracks." }, "genius_pageviews": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Total Genius page-view count for the artist." }, "genreRank": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ], "description": "Name of the top genre." }, "rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank within the top genre." } } }, "subGenreRank1": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ], "description": "Name of the first top sub-genre." }, "rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank within the first top sub-genre." } } }, "subGenreRank2": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ], "description": "Name of the second top sub-genre." }, "rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank within the second top sub-genre." } } }, "countryRank": { "type": [ "object", "null" ], "properties": { "country": { "type": [ "string", "null" ], "description": "Country name." }, "rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank within the country." } }, "description": "Artist's rank within their primary country." } }, "description": "Absolute change in platform metrics versus 28 days ago." }, "monthly_diff_percent": { "type": [ "object", "null" ], "properties": { "sp_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Spotify follower count." }, "sp_monthly_listeners": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Spotify monthly listener count." }, "sp_popularity": { "type": [ "number", "null" ], "format": "float", "description": "Spotify popularity score (0–100)." }, "sp_listeners_to_followers_ratio": { "type": [ "number", "null" ], "format": "float", "description": "Ratio of Spotify monthly listeners to Spotify followers." }, "sp_followers_to_listeners_ratio": { "type": [ "number", "null" ], "format": "float", "description": "Ratio of Spotify followers to Spotify monthly listeners." }, "deezer_fans": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Deezer fan count." }, "fs_likes": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Facebook page-like count." }, "fs_talks": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Facebook people-talking-about count: users discussing or interacting with the page." }, "ins_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Instagram follower count." }, "ts_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Twitter/X follower count." }, "ts_retweets": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Twitter/X retweet count." }, "ycs_views": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "YouTube channel total view count." }, "ycs_subscribers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "YouTube channel subscriber count." }, "youtube_daily_video_views": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "YouTube daily video view count." }, "youtube_monthly_video_views": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "YouTube monthly video view count." }, "ws_views": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Wikipedia page-view count." }, "soundcloud_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "SoundCloud follower count." }, "bs_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Bandsintown follower count." }, "tiktok_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "TikTok follower count." }, "tiktok_likes": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "TikTok total like count." }, "cm_artist_rank": { "type": [ "number", "null" ], "format": "float", "description": "Global Chartmetric artist rank (1 is highest)." }, "sp_followers_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Spotify followers." }, "sp_popularity_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Spotify popularity." }, "sp_monthly_listeners_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Spotify monthly listeners." }, "sp_where_people_listen": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "code2": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-2 country code of the listener location." }, "listeners": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Spotify monthly listener count for this location. May arrive as string (uncast aggregate)." }, "name": { "type": [ "string", "null" ], "description": "City or country name of the listener location." } } }, "description": "Top Spotify listener locations (countries/cities)." }, "deezer_fans_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Deezer fans." }, "ins_followers_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Instagram followers." }, "ycs_subscribers_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by YouTube channel subscribers." }, "ycs_views_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by YouTube channel views." }, "tiktok_followers_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by TikTok followers." }, "tiktok_likes_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by TikTok likes." }, "tiktok_top_video_views": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Top TikTok video view count." }, "tiktok_top_video_views_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by top TikTok video views." }, "tiktok_top_video_comments": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Top TikTok video comment count." }, "tiktok_top_video_comments_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by top TikTok video comments." }, "tiktok_track_posts": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Total TikTok posts using the artist’s tracks." }, "tiktok_track_posts_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by TikTok track posts." }, "twitter_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Twitter follower count." }, "twitter_followers_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Twitter followers." }, "line_music_artist_likes": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Line Music artist like count." }, "line_music_artist_likes_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Line Music artist likes." }, "line_music_likes": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Line Music track-likes total." }, "line_music_likes_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Line Music likes." }, "line_music_plays": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Line Music play count." }, "line_music_plays_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Line Music plays." }, "line_music_mv_plays": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Line Music music-video play count." }, "fan_base_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric fan-base composite rank." }, "engagement_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric engagement composite rank." }, "youtube_daily_video_views_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by YouTube daily video views." }, "youtube_monthly_video_views_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by YouTube monthly video views." }, "twitch_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Twitch follower count." }, "twitch_followers_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Twitch followers." }, "twitch_views": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Twitch total view count." }, "twitch_views_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Twitch views." }, "twitch_monthly_viewer_hours": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Twitch monthly viewer-hours." }, "twitch_monthly_viewer_hours_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Twitch monthly viewer-hours." }, "twitch_weekly_viewer_hours": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Twitch weekly viewer-hours." }, "twitch_weekly_viewer_hours_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Twitch weekly viewer-hours." }, "pandora_listeners_28_day": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Pandora 28-day listener count." }, "pandora_listeners_28_day_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Pandora 28-day listeners." }, "pandora_lifetime_stations_added": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Pandora lifetime stations-added count." }, "pandora_lifetime_stations_added_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Pandora lifetime stations added." }, "pandora_lifetime_streams": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Pandora lifetime stream count." }, "pandora_lifetime_streams_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Pandora lifetime streams." }, "boomplay_ranking_current": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Current Boomplay ranking." }, "boomplay_ranking_current_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by current Boomplay ranking." }, "boomplay_favorites": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Boomplay favorite count." }, "boomplay_favorites_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Boomplay favorites." }, "boomplay_shares": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Boomplay share count." }, "boomplay_shares_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Boomplay shares." }, "boomplay_comments": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Boomplay comment count." }, "boomplay_comments_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Boomplay comments." }, "boomplay_plays": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Boomplay play count." }, "boomplay_plays_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Boomplay plays." }, "num_sp_editorial_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of Spotify editorial playlists featuring this artist." }, "num_sp_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of Spotify playlists featuring this artist." }, "sp_playlist_total_reach": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Sum of followers from all Spotify playlists featuring this artist." }, "sp_editorial_playlist_total_reach": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Sum of followers from all Spotify editorial playlists featuring this artist." }, "num_am_editorial_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of Apple Music editorial playlists featuring this artist." }, "num_am_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of Apple Music playlists featuring this artist." }, "num_de_editorial_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of Deezer editorial playlists featuring this artist." }, "num_de_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of Deezer playlists featuring this artist." }, "de_playlist_total_reach": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Sum of fans from all Deezer playlists featuring this artist." }, "de_editorial_playlist_total_reach": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Sum of fans from all Deezer editorial playlists featuring this artist." }, "num_az_editorial_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of Amazon editorial playlists featuring this artist." }, "num_az_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of Amazon playlists featuring this artist." }, "num_yt_editorial_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of YouTube editorial playlists featuring this artist." }, "num_yt_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of YouTube playlists featuring this artist." }, "yt_playlist_total_reach": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Sum of views from all YouTube playlists featuring this artist." }, "yt_editorial_playlist_total_reach": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Sum of views from all YouTube editorial playlists featuring this artist." }, "shazam_count": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Sum of Shazam plays across the artist's tracks." }, "genius_pageviews": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Total Genius page-view count for the artist." }, "genreRank": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ], "description": "Name of the top genre." }, "rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank within the top genre." } } }, "subGenreRank1": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ], "description": "Name of the first top sub-genre." }, "rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank within the first top sub-genre." } } }, "subGenreRank2": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ], "description": "Name of the second top sub-genre." }, "rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank within the second top sub-genre." } } }, "countryRank": { "type": [ "object", "null" ], "properties": { "country": { "type": [ "string", "null" ], "description": "Country name." }, "rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank within the country." } }, "description": "Artist's rank within their primary country." } }, "description": "Percentage change in platform metrics versus 28 days ago." }, "bimonthly_diff": { "type": [ "object", "null" ], "properties": { "sp_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Spotify follower count." }, "sp_monthly_listeners": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Spotify monthly listener count." }, "sp_popularity": { "type": [ "number", "null" ], "format": "float", "description": "Spotify popularity score (0–100)." }, "sp_listeners_to_followers_ratio": { "type": [ "number", "null" ], "format": "float", "description": "Ratio of Spotify monthly listeners to Spotify followers." }, "sp_followers_to_listeners_ratio": { "type": [ "number", "null" ], "format": "float", "description": "Ratio of Spotify followers to Spotify monthly listeners." }, "deezer_fans": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Deezer fan count." }, "fs_likes": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Facebook page-like count." }, "fs_talks": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Facebook people-talking-about count: users discussing or interacting with the page." }, "ins_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Instagram follower count." }, "ts_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Twitter/X follower count." }, "ts_retweets": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Twitter/X retweet count." }, "ycs_views": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "YouTube channel total view count." }, "ycs_subscribers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "YouTube channel subscriber count." }, "youtube_daily_video_views": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "YouTube daily video view count." }, "youtube_monthly_video_views": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "YouTube monthly video view count." }, "ws_views": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Wikipedia page-view count." }, "soundcloud_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "SoundCloud follower count." }, "bs_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Bandsintown follower count." }, "tiktok_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "TikTok follower count." }, "tiktok_likes": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "TikTok total like count." }, "cm_artist_rank": { "type": [ "number", "null" ], "format": "float", "description": "Global Chartmetric artist rank (1 is highest)." }, "sp_followers_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Spotify followers." }, "sp_popularity_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Spotify popularity." }, "sp_monthly_listeners_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Spotify monthly listeners." }, "sp_where_people_listen": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "code2": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-2 country code of the listener location." }, "listeners": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Spotify monthly listener count for this location. May arrive as string (uncast aggregate)." }, "name": { "type": [ "string", "null" ], "description": "City or country name of the listener location." } } }, "description": "Top Spotify listener locations (countries/cities)." }, "deezer_fans_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Deezer fans." }, "ins_followers_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Instagram followers." }, "ycs_subscribers_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by YouTube channel subscribers." }, "ycs_views_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by YouTube channel views." }, "tiktok_followers_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by TikTok followers." }, "tiktok_likes_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by TikTok likes." }, "tiktok_top_video_views": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Top TikTok video view count." }, "tiktok_top_video_views_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by top TikTok video views." }, "tiktok_top_video_comments": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Top TikTok video comment count." }, "tiktok_top_video_comments_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by top TikTok video comments." }, "tiktok_track_posts": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Total TikTok posts using the artist’s tracks." }, "tiktok_track_posts_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by TikTok track posts." }, "twitter_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Twitter follower count." }, "twitter_followers_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Twitter followers." }, "line_music_artist_likes": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Line Music artist like count." }, "line_music_artist_likes_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Line Music artist likes." }, "line_music_likes": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Line Music track-likes total." }, "line_music_likes_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Line Music likes." }, "line_music_plays": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Line Music play count." }, "line_music_plays_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Line Music plays." }, "line_music_mv_plays": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Line Music music-video play count." }, "fan_base_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric fan-base composite rank." }, "engagement_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric engagement composite rank." }, "youtube_daily_video_views_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by YouTube daily video views." }, "youtube_monthly_video_views_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by YouTube monthly video views." }, "twitch_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Twitch follower count." }, "twitch_followers_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Twitch followers." }, "twitch_views": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Twitch total view count." }, "twitch_views_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Twitch views." }, "twitch_monthly_viewer_hours": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Twitch monthly viewer-hours." }, "twitch_monthly_viewer_hours_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Twitch monthly viewer-hours." }, "twitch_weekly_viewer_hours": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Twitch weekly viewer-hours." }, "twitch_weekly_viewer_hours_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Twitch weekly viewer-hours." }, "pandora_listeners_28_day": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Pandora 28-day listener count." }, "pandora_listeners_28_day_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Pandora 28-day listeners." }, "pandora_lifetime_stations_added": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Pandora lifetime stations-added count." }, "pandora_lifetime_stations_added_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Pandora lifetime stations added." }, "pandora_lifetime_streams": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Pandora lifetime stream count." }, "pandora_lifetime_streams_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Pandora lifetime streams." }, "boomplay_ranking_current": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Current Boomplay ranking." }, "boomplay_ranking_current_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by current Boomplay ranking." }, "boomplay_favorites": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Boomplay favorite count." }, "boomplay_favorites_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Boomplay favorites." }, "boomplay_shares": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Boomplay share count." }, "boomplay_shares_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Boomplay shares." }, "boomplay_comments": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Boomplay comment count." }, "boomplay_comments_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Boomplay comments." }, "boomplay_plays": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Boomplay play count." }, "boomplay_plays_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Boomplay plays." }, "num_sp_editorial_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of Spotify editorial playlists featuring this artist." }, "num_sp_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of Spotify playlists featuring this artist." }, "sp_playlist_total_reach": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Sum of followers from all Spotify playlists featuring this artist." }, "sp_editorial_playlist_total_reach": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Sum of followers from all Spotify editorial playlists featuring this artist." }, "num_am_editorial_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of Apple Music editorial playlists featuring this artist." }, "num_am_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of Apple Music playlists featuring this artist." }, "num_de_editorial_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of Deezer editorial playlists featuring this artist." }, "num_de_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of Deezer playlists featuring this artist." }, "de_playlist_total_reach": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Sum of fans from all Deezer playlists featuring this artist." }, "de_editorial_playlist_total_reach": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Sum of fans from all Deezer editorial playlists featuring this artist." }, "num_az_editorial_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of Amazon editorial playlists featuring this artist." }, "num_az_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of Amazon playlists featuring this artist." }, "num_yt_editorial_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of YouTube editorial playlists featuring this artist." }, "num_yt_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of YouTube playlists featuring this artist." }, "yt_playlist_total_reach": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Sum of views from all YouTube playlists featuring this artist." }, "yt_editorial_playlist_total_reach": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Sum of views from all YouTube editorial playlists featuring this artist." }, "shazam_count": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Sum of Shazam plays across the artist's tracks." }, "genius_pageviews": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Total Genius page-view count for the artist." }, "genreRank": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ], "description": "Name of the top genre." }, "rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank within the top genre." } } }, "subGenreRank1": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ], "description": "Name of the first top sub-genre." }, "rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank within the first top sub-genre." } } }, "subGenreRank2": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ], "description": "Name of the second top sub-genre." }, "rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank within the second top sub-genre." } } }, "countryRank": { "type": [ "object", "null" ], "properties": { "country": { "type": [ "string", "null" ], "description": "Country name." }, "rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank within the country." } }, "description": "Artist's rank within their primary country." } }, "description": "Absolute change in platform metrics versus 56 days ago." }, "bimonthly_diff_percent": { "type": [ "object", "null" ], "properties": { "sp_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Spotify follower count." }, "sp_monthly_listeners": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Spotify monthly listener count." }, "sp_popularity": { "type": [ "number", "null" ], "format": "float", "description": "Spotify popularity score (0–100)." }, "sp_listeners_to_followers_ratio": { "type": [ "number", "null" ], "format": "float", "description": "Ratio of Spotify monthly listeners to Spotify followers." }, "sp_followers_to_listeners_ratio": { "type": [ "number", "null" ], "format": "float", "description": "Ratio of Spotify followers to Spotify monthly listeners." }, "deezer_fans": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Deezer fan count." }, "fs_likes": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Facebook page-like count." }, "fs_talks": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Facebook people-talking-about count: users discussing or interacting with the page." }, "ins_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Instagram follower count." }, "ts_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Twitter/X follower count." }, "ts_retweets": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Twitter/X retweet count." }, "ycs_views": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "YouTube channel total view count." }, "ycs_subscribers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "YouTube channel subscriber count." }, "youtube_daily_video_views": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "YouTube daily video view count." }, "youtube_monthly_video_views": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "YouTube monthly video view count." }, "ws_views": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Wikipedia page-view count." }, "soundcloud_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "SoundCloud follower count." }, "bs_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Bandsintown follower count." }, "tiktok_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "TikTok follower count." }, "tiktok_likes": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "TikTok total like count." }, "cm_artist_rank": { "type": [ "number", "null" ], "format": "float", "description": "Global Chartmetric artist rank (1 is highest)." }, "sp_followers_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Spotify followers." }, "sp_popularity_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Spotify popularity." }, "sp_monthly_listeners_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Spotify monthly listeners." }, "sp_where_people_listen": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "code2": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-2 country code of the listener location." }, "listeners": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Spotify monthly listener count for this location. May arrive as string (uncast aggregate)." }, "name": { "type": [ "string", "null" ], "description": "City or country name of the listener location." } } }, "description": "Top Spotify listener locations (countries/cities)." }, "deezer_fans_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Deezer fans." }, "ins_followers_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Instagram followers." }, "ycs_subscribers_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by YouTube channel subscribers." }, "ycs_views_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by YouTube channel views." }, "tiktok_followers_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by TikTok followers." }, "tiktok_likes_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by TikTok likes." }, "tiktok_top_video_views": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Top TikTok video view count." }, "tiktok_top_video_views_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by top TikTok video views." }, "tiktok_top_video_comments": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Top TikTok video comment count." }, "tiktok_top_video_comments_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by top TikTok video comments." }, "tiktok_track_posts": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Total TikTok posts using the artist’s tracks." }, "tiktok_track_posts_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by TikTok track posts." }, "twitter_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Twitter follower count." }, "twitter_followers_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Twitter followers." }, "line_music_artist_likes": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Line Music artist like count." }, "line_music_artist_likes_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Line Music artist likes." }, "line_music_likes": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Line Music track-likes total." }, "line_music_likes_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Line Music likes." }, "line_music_plays": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Line Music play count." }, "line_music_plays_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Line Music plays." }, "line_music_mv_plays": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Line Music music-video play count." }, "fan_base_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric fan-base composite rank." }, "engagement_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric engagement composite rank." }, "youtube_daily_video_views_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by YouTube daily video views." }, "youtube_monthly_video_views_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by YouTube monthly video views." }, "twitch_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Twitch follower count." }, "twitch_followers_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Twitch followers." }, "twitch_views": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Twitch total view count." }, "twitch_views_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Twitch views." }, "twitch_monthly_viewer_hours": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Twitch monthly viewer-hours." }, "twitch_monthly_viewer_hours_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Twitch monthly viewer-hours." }, "twitch_weekly_viewer_hours": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Twitch weekly viewer-hours." }, "twitch_weekly_viewer_hours_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Twitch weekly viewer-hours." }, "pandora_listeners_28_day": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Pandora 28-day listener count." }, "pandora_listeners_28_day_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Pandora 28-day listeners." }, "pandora_lifetime_stations_added": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Pandora lifetime stations-added count." }, "pandora_lifetime_stations_added_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Pandora lifetime stations added." }, "pandora_lifetime_streams": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Pandora lifetime stream count." }, "pandora_lifetime_streams_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Pandora lifetime streams." }, "boomplay_ranking_current": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Current Boomplay ranking." }, "boomplay_ranking_current_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by current Boomplay ranking." }, "boomplay_favorites": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Boomplay favorite count." }, "boomplay_favorites_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Boomplay favorites." }, "boomplay_shares": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Boomplay share count." }, "boomplay_shares_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Boomplay shares." }, "boomplay_comments": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Boomplay comment count." }, "boomplay_comments_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Boomplay comments." }, "boomplay_plays": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Boomplay play count." }, "boomplay_plays_rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank by Boomplay plays." }, "num_sp_editorial_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of Spotify editorial playlists featuring this artist." }, "num_sp_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of Spotify playlists featuring this artist." }, "sp_playlist_total_reach": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Sum of followers from all Spotify playlists featuring this artist." }, "sp_editorial_playlist_total_reach": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Sum of followers from all Spotify editorial playlists featuring this artist." }, "num_am_editorial_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of Apple Music editorial playlists featuring this artist." }, "num_am_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of Apple Music playlists featuring this artist." }, "num_de_editorial_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of Deezer editorial playlists featuring this artist." }, "num_de_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of Deezer playlists featuring this artist." }, "de_playlist_total_reach": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Sum of fans from all Deezer playlists featuring this artist." }, "de_editorial_playlist_total_reach": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Sum of fans from all Deezer editorial playlists featuring this artist." }, "num_az_editorial_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of Amazon editorial playlists featuring this artist." }, "num_az_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of Amazon playlists featuring this artist." }, "num_yt_editorial_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of YouTube editorial playlists featuring this artist." }, "num_yt_playlists": { "type": [ "number", "null" ], "format": "float", "description": "Number of YouTube playlists featuring this artist." }, "yt_playlist_total_reach": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Sum of views from all YouTube playlists featuring this artist." }, "yt_editorial_playlist_total_reach": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Sum of views from all YouTube editorial playlists featuring this artist." }, "shazam_count": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Sum of Shazam plays across the artist's tracks." }, "genius_pageviews": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Total Genius page-view count for the artist." }, "genreRank": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ], "description": "Name of the top genre." }, "rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank within the top genre." } } }, "subGenreRank1": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ], "description": "Name of the first top sub-genre." }, "rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank within the first top sub-genre." } } }, "subGenreRank2": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ], "description": "Name of the second top sub-genre." }, "rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank within the second top sub-genre." } } }, "countryRank": { "type": [ "object", "null" ], "properties": { "country": { "type": [ "string", "null" ], "description": "Country name." }, "rank": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric rank within the country." } }, "description": "Artist's rank within their primary country." } }, "description": "Percentage change in platform metrics versus 56 days ago." } } } }, "additionalProperties": false }, "examples": { "default": { "value": { "obj": { "timestamp": "2025-10-16T09:39:26Z", "latest": { "sp_followers": 51385645, "deezer_fans": 5500765, "sp_popularity": 88, "sp_monthly_listeners": 61398738, "ins_followers": 22894076, "ycs_subscribers": 17900000, "cm_artist_rank": 40, "cm_artist_rank_percentile": 1, "fan_base_rank": 53, "engagement_rank": 39, "artist_score": 97.58563625103979, "sp_popularity_rank": 22, "sp_followers_rank": 24, "sp_monthly_listeners_rank": 28 }, "weekly_diff": { "sp_followers": 164715, "deezer_fans": 8033, "sp_popularity": -1, "sp_monthly_listeners": 814320, "ins_followers": 80124 }, "weekly_diff_percent": { "sp_followers": 0.3216, "deezer_fans": 0.1462, "sp_popularity": -1.1236, "sp_monthly_listeners": 1.3441, "ins_followers": 0.3512 }, "monthly_diff": { "sp_followers": 664715, "sp_monthly_listeners": 2814320 }, "monthly_diff_percent": { "sp_followers": 1.31, "sp_monthly_listeners": 4.81 }, "bimonthly_diff": { "sp_followers": 1264715 }, "bimonthly_diff_percent": { "sp_followers": 2.56 } } } } } } } } } } }, "/api/brand/list": { "get": { "summary": "List Brand Names (deprecated)", "tags": [ "Brand" ], "operationId": "listBrandNames", "description": "**Deprecated — removed after 2026-10-01. Use `GET /api/brand/v2/list` instead.** List all Chartmetric brand IDs and names. Note that V2 reads a different brand universe, so IDs are not interchangeable.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric brand ID." }, "name": { "type": "string", "description": "Brand name." } }, "required": [ "id", "name" ] } } }, "required": [ "obj" ], "additionalProperties": false }, "examples": { "default": { "value": { "obj": [ { "id": 2, "name": "20th Century Fox" }, { "id": 10787, "name": "24Classics" } ] } } } } } } } } }, "/api/brand/list/by/interest": { "get": { "summary": "List Brands by Interest Category (deprecated)", "tags": [ "Brand" ], "operationId": "listBrandsByInterest", "description": "**Deprecated — removed after 2026-10-01. Use `GET /api/brand/v2/list/by/category` instead.** Brands grouped by interest category. The response is keyed by interest name (e.g. `Music`, `Electronics & Computers`) with up to 20 brands per category. Note: `sortColumn` is accepted for API compatibility but the handler currently returns a fixed ordering.", "parameters": [ { "name": "sortColumn", "in": "query", "schema": { "type": "string", "enum": [ "followers", "likers" ], "description": "Column used to order interest groups. One of `followers`, `likers`. Defaults to `followers`.", "default": "followers" }, "required": false, "description": "Column used to order interest groups. One of `followers`, `likers`. Defaults to `followers`." }, { "name": "brandCount", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "description": "Maximum number of brands returned per interest category. Defaults to 10, max 50.", "default": 10 }, "required": false, "description": "Maximum number of brands returned per interest category. Defaults to 10, max 50." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "object", "properties": {}, "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "brand_id": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric brand ID." }, "brand_name": { "type": [ "string", "null" ], "description": "Brand name." }, "interest_id": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric interest category ID." }, "interest_name": { "type": [ "string", "null" ], "description": "Interest category name (e.g. `Music`, `Electronics & Computers`)." }, "followers": { "type": [ "integer", "null" ], "minimum": 0, "description": "Sum of Instagram followers across artists whose audience is interested in this brand." }, "artist_count": { "type": [ "integer", "null" ], "minimum": 0, "description": "Number of artists with at least one Instagram follower interested in this brand." } }, "required": [ "brand_id", "interest_id" ] } } } }, "additionalProperties": false }, "examples": { "default": { "value": { "obj": { "Electronics & Computers": [ { "brand_id": 138, "brand_name": "Apple", "interest_id": 25, "interest_name": "Electronics & Computers", "followers": 3305301635, "artist_count": 141435 } ], "Music": [] } } } } } } } } } }, "/api/brand/v2/list": { "get": { "summary": "List Brand Names (V2)", "tags": [ "Brand" ], "operationId": "listBrandNamesV2", "description": "Every Chartmetric brand ID and name. Replaces `GET /api/brand/list`, which reads a different brand universe — IDs are not interchangeable between the two.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric brand ID." }, "name": { "type": "string", "description": "Brand name." } }, "required": [ "id", "name" ] } } }, "required": [ "obj" ], "additionalProperties": false }, "examples": { "default": { "value": { "obj": [ { "id": 138, "name": "Apple" }, { "id": 2, "name": "20th Century Fox" } ] } } } } } } } } }, "/api/brand/v2/list/by/category": { "get": { "summary": "List Brands by Category (V2)", "tags": [ "Brand" ], "operationId": "listBrandsByCategory", "description": "Brands filtered by category, with the brand’s own follower counts on each supported platform.\n\nReplaces `GET /api/brand/list/by/interest`. Three differences worth noting when migrating:\n\n| V1 | V2 |\n|---|---|\n| Response is a map keyed by category name | Response is a flat `data` array with `total` and `facets` |\n| Fixed 20 brands per category, `brandCount` ignored | `limit` / `offset` honored |\n| `followers` = summed Instagram followers of *artists* interested in the brand | `instagram_followers` / `tiktok_followers` = the *brand’s own* account followers |\n\nThe `interest_id` field has no V2 equivalent: categories are derived tags rather than rows with IDs. Use the category name, which `facets.categories` enumerates.", "parameters": [ { "name": "category", "in": "query", "schema": { "type": "string", "maxLength": 200, "description": "Restrict results to a single brand category (e.g. `Music`, `Electronics & Computers`). Omit to search across every category. The `facets.categories` block of the response lists every value accepted here." }, "required": false, "description": "Restrict results to a single brand category (e.g. `Music`, `Electronics & Computers`). Omit to search across every category. The `facets.categories` block of the response lists every value accepted here." }, { "name": "search", "in": "query", "schema": { "type": "string", "maxLength": 200, "description": "Free-text search over brand names. Omit to search across every brand." }, "required": false, "description": "Free-text search over brand names. Omit to search across every brand." }, { "name": "sortColumn", "in": "query", "schema": { "type": "string", "enum": [ "name", "artistCount", "instagramFollowers", "tiktokFollowers" ], "description": "Column used to sort brands. One of `name`, `artistCount`, `instagramFollowers`, `tiktokFollowers`. Defaults to `instagramFollowers`.", "default": "instagramFollowers" }, "required": false, "description": "Column used to sort brands. One of `name`, `artistCount`, `instagramFollowers`, `tiktokFollowers`. Defaults to `instagramFollowers`." }, { "name": "sortOrderDesc", "in": "query", "schema": { "type": "boolean", "description": "If true (default), sort `sortColumn` in descending order.", "default": true }, "required": false, "description": "If true (default), sort `sortColumn` in descending order." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum number of brands to return. Defaults to 20, max 100.", "default": 20 }, "required": false, "description": "Maximum number of brands to return. Defaults to 20, max 100." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, "required": false, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, { "name": "countries[]", "in": "query", "schema": { "type": "array", "items": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB')." }, "description": "Restrict results to brands based in these countries, as ISO 3166-1 alpha-2 codes (e.g. 'US', 'BR')." }, "required": false, "description": "Restrict results to brands based in these countries, as ISO 3166-1 alpha-2 codes (e.g. 'US', 'BR')." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric brand ID." }, "name": { "type": "string", "description": "Brand name." }, "image_url": { "type": [ "string", "null" ], "description": "Brand logo or profile image URL." }, "category": { "type": [ "string", "null" ], "description": "Primary brand category (e.g. `Music`, `Electronics & Computers`)." }, "country": { "type": [ "string", "null" ], "description": "Country the brand is based in, as an ISO 3166-1 alpha-2 code (e.g. 'US')." }, "description": { "type": [ "string", "null" ], "description": "Short brand description." }, "instagram_followers": { "type": "integer", "minimum": 0, "description": "Followers on the brand's own Instagram account. 0 when unavailable." }, "tiktok_followers": { "type": "integer", "minimum": 0, "description": "Followers on the brand's own TikTok account. 0 when unavailable." }, "youtube_followers": { "type": "integer", "minimum": 0, "description": "Subscribers on the brand's own YouTube channel. 0 when unavailable." }, "social_links": { "type": "object", "properties": { "instagram": { "type": [ "string", "null" ], "description": "URL of the brand's Instagram account." }, "tiktok": { "type": [ "string", "null" ], "description": "URL of the brand's TikTok account." }, "youtube": { "type": [ "string", "null" ], "description": "URL of the brand's YouTube channel." } }, "description": "Links to the brand's own social accounts. Each entry is null when no account is linked on that platform." }, "artist_count": { "type": "integer", "minimum": 0, "description": "Number of artists whose audience matches this brand." } }, "required": [ "id", "name", "instagram_followers", "tiktok_followers", "youtube_followers", "social_links", "artist_count" ] }, "description": "Brands matching the filters, sorted and paginated as requested." }, "total": { "type": "integer", "minimum": 0, "description": "Total number of brands matching the filters, ignoring `limit` / `offset`." }, "facets": { "type": "object", "properties": { "categories": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Facet value, usable as a filter parameter." }, "count": { "type": "integer", "minimum": 0, "description": "Number of brands carrying this value." } }, "required": [ "name", "count" ] }, "description": "Every category present in the unfiltered result set, with brand counts." }, "subcategories": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Facet value, usable as a filter parameter." }, "count": { "type": "integer", "minimum": 0, "description": "Number of brands carrying this value." } }, "required": [ "name", "count" ] }, "description": "Every sub-category present in the unfiltered result set, with brand counts." }, "countries": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code." }, "count": { "type": "integer", "minimum": 0, "description": "Number of brands based in this country." } }, "required": [ "code", "count" ] }, "description": "Every brand country present in the unfiltered result set, with brand counts." } }, "required": [ "categories", "subcategories", "countries" ], "description": "Valid values for the filter parameters, with per-value brand counts." } }, "required": [ "data", "total", "facets" ] } }, "additionalProperties": false }, "examples": { "default": { "value": { "obj": { "data": [ { "id": 138, "name": "Apple", "image_url": "https://storage.googleapis.com/cm-brand-images/138.jpg", "category": "Electronics & Computers", "country": "US", "description": "Consumer electronics and software company.", "instagram_followers": 33500000, "tiktok_followers": 2100000, "youtube_followers": 19800000, "social_links": { "instagram": "https://www.instagram.com/apple", "tiktok": "https://www.tiktok.com/@apple", "youtube": "https://www.youtube.com/@Apple" }, "artist_count": 141435 } ], "total": 1, "facets": { "categories": [ { "name": "Electronics & Computers", "count": 412 } ], "subcategories": [ { "name": "Smartphones", "count": 37 } ], "countries": [ { "code": "US", "count": 288 } ] } } } } } } } } } } }, "/api/brand/v2/list/by/subcategory": { "get": { "summary": "List Brands by Sub-Category (V2)", "tags": [ "Brand" ], "operationId": "listBrandsBySubcategory", "description": "Brands filtered by sub-category. Identical to List Brands by Category except that the `subcategory` parameter filters on the brand’s finer-grained tags; `facets.subcategories` enumerates the accepted values. New in V2 — there is no V1 equivalent.", "parameters": [ { "name": "subcategory", "in": "query", "schema": { "type": "string", "maxLength": 200, "description": "Restrict results to a single brand sub-category. Omit to search across every sub-category. The `facets.subcategories` block of the response lists every value accepted here." }, "required": false, "description": "Restrict results to a single brand sub-category. Omit to search across every sub-category. The `facets.subcategories` block of the response lists every value accepted here." }, { "name": "search", "in": "query", "schema": { "type": "string", "maxLength": 200, "description": "Free-text search over brand names. Omit to search across every brand." }, "required": false, "description": "Free-text search over brand names. Omit to search across every brand." }, { "name": "sortColumn", "in": "query", "schema": { "type": "string", "enum": [ "name", "artistCount", "instagramFollowers", "tiktokFollowers" ], "description": "Column used to sort brands. One of `name`, `artistCount`, `instagramFollowers`, `tiktokFollowers`. Defaults to `instagramFollowers`.", "default": "instagramFollowers" }, "required": false, "description": "Column used to sort brands. One of `name`, `artistCount`, `instagramFollowers`, `tiktokFollowers`. Defaults to `instagramFollowers`." }, { "name": "sortOrderDesc", "in": "query", "schema": { "type": "boolean", "description": "If true (default), sort `sortColumn` in descending order.", "default": true }, "required": false, "description": "If true (default), sort `sortColumn` in descending order." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum number of brands to return. Defaults to 20, max 100.", "default": 20 }, "required": false, "description": "Maximum number of brands to return. Defaults to 20, max 100." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, "required": false, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, { "name": "countries[]", "in": "query", "schema": { "type": "array", "items": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB')." }, "description": "Restrict results to brands based in these countries, as ISO 3166-1 alpha-2 codes (e.g. 'US', 'BR')." }, "required": false, "description": "Restrict results to brands based in these countries, as ISO 3166-1 alpha-2 codes (e.g. 'US', 'BR')." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric brand ID." }, "name": { "type": "string", "description": "Brand name." }, "image_url": { "type": [ "string", "null" ], "description": "Brand logo or profile image URL." }, "category": { "type": [ "string", "null" ], "description": "Primary brand category (e.g. `Music`, `Electronics & Computers`)." }, "country": { "type": [ "string", "null" ], "description": "Country the brand is based in, as an ISO 3166-1 alpha-2 code (e.g. 'US')." }, "description": { "type": [ "string", "null" ], "description": "Short brand description." }, "instagram_followers": { "type": "integer", "minimum": 0, "description": "Followers on the brand's own Instagram account. 0 when unavailable." }, "tiktok_followers": { "type": "integer", "minimum": 0, "description": "Followers on the brand's own TikTok account. 0 when unavailable." }, "youtube_followers": { "type": "integer", "minimum": 0, "description": "Subscribers on the brand's own YouTube channel. 0 when unavailable." }, "social_links": { "type": "object", "properties": { "instagram": { "type": [ "string", "null" ], "description": "URL of the brand's Instagram account." }, "tiktok": { "type": [ "string", "null" ], "description": "URL of the brand's TikTok account." }, "youtube": { "type": [ "string", "null" ], "description": "URL of the brand's YouTube channel." } }, "description": "Links to the brand's own social accounts. Each entry is null when no account is linked on that platform." }, "artist_count": { "type": "integer", "minimum": 0, "description": "Number of artists whose audience matches this brand." } }, "required": [ "id", "name", "instagram_followers", "tiktok_followers", "youtube_followers", "social_links", "artist_count" ] }, "description": "Brands matching the filters, sorted and paginated as requested." }, "total": { "type": "integer", "minimum": 0, "description": "Total number of brands matching the filters, ignoring `limit` / `offset`." }, "facets": { "type": "object", "properties": { "categories": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Facet value, usable as a filter parameter." }, "count": { "type": "integer", "minimum": 0, "description": "Number of brands carrying this value." } }, "required": [ "name", "count" ] }, "description": "Every category present in the unfiltered result set, with brand counts." }, "subcategories": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Facet value, usable as a filter parameter." }, "count": { "type": "integer", "minimum": 0, "description": "Number of brands carrying this value." } }, "required": [ "name", "count" ] }, "description": "Every sub-category present in the unfiltered result set, with brand counts." }, "countries": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code." }, "count": { "type": "integer", "minimum": 0, "description": "Number of brands based in this country." } }, "required": [ "code", "count" ] }, "description": "Every brand country present in the unfiltered result set, with brand counts." } }, "required": [ "categories", "subcategories", "countries" ], "description": "Valid values for the filter parameters, with per-value brand counts." } }, "required": [ "data", "total", "facets" ] } }, "additionalProperties": false }, "examples": { "default": { "value": { "obj": { "data": [ { "id": 138, "name": "Apple", "image_url": "https://storage.googleapis.com/cm-brand-images/138.jpg", "category": "Electronics & Computers", "country": "US", "description": "Consumer electronics and software company.", "instagram_followers": 33500000, "tiktok_followers": 2100000, "youtube_followers": 19800000, "social_links": { "instagram": "https://www.instagram.com/apple", "tiktok": "https://www.tiktok.com/@apple", "youtube": "https://www.youtube.com/@Apple" }, "artist_count": 141435 } ], "total": 1, "facets": { "categories": [ { "name": "Electronics & Computers", "count": 412 } ], "subcategories": [ { "name": "Smartphones", "count": 37 } ], "countries": [ { "code": "US", "count": 288 } ] } } } } } } } } } } }, "/api/brand/v2/{brandId}/audience": { "get": { "summary": "💎 Premium — Brand Audience", "tags": [ "Brand" ], "operationId": "getBrandAudienceV2", "description": "The brand's own audience breakdown on a given platform — gender and age split, plus the countries, languages and ethnicities its followers skew toward.\n\nSourced from the brand's own account rather than from the artists matched to it. Mirrors the artist audience endpoints; the brand profile at `GET /api/brand/v2/{brandId}` does not carry this data.\n\nEvery weight is a `0`-`1` fraction. `top_ethnicities` is Instagram-only and comes back empty when `platform` is `tiktok` or `youtube`. When no report exists for the brand on the requested platform, `source_platform` is `null` and the lists are empty.", "parameters": [ { "name": "brandId", "in": "path", "schema": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric brand ID." }, "required": true, "description": "Chartmetric brand ID.", "examples": { "default": { "value": 1 } } }, { "name": "platform", "in": "query", "schema": { "type": "string", "enum": [ "instagram", "tiktok", "youtube" ], "description": "Platform the audience breakdown is sourced from. One of `instagram`, `tiktok`, `youtube`. Defaults to `instagram`. Ethnicity data exists on Instagram only, so `top_ethnicities` is empty for the other platforms.", "default": "instagram" }, "required": false, "description": "Platform the audience breakdown is sourced from. One of `instagram`, `tiktok`, `youtube`. Defaults to `instagram`. Ethnicity data exists on Instagram only, so `top_ethnicities` is empty for the other platforms." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "object", "properties": { "source_platform": { "type": [ "string", "null" ], "description": "Platform the breakdown was sourced from. Null when no report was available." }, "demographics": { "type": [ "object", "null" ], "properties": { "male_percent": { "type": [ "number", "null" ], "format": "float", "description": "Share of the audience that is male, 0-1." }, "female_percent": { "type": [ "number", "null" ], "format": "float", "description": "Share of the audience that is female, 0-1." }, "age_groups": { "type": "object", "properties": {}, "additionalProperties": { "type": "number", "format": "float" }, "description": "Share of the audience per age bracket, keyed by bracket, 0-1." } }, "description": "Age and gender split. Null when unavailable." }, "top_countries": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": [ "string", "null" ], "description": "Code identifying the country." }, "name": { "type": [ "string", "null" ], "description": "Display name of the country." }, "weight": { "type": [ "number", "null" ], "format": "float", "description": "Share of the audience, as a 0-1 fraction." } } }, "description": "Countries the audience is concentrated in, strongest first." }, "top_languages": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": [ "string", "null" ], "description": "Code identifying the language." }, "name": { "type": [ "string", "null" ], "description": "Display name of the language." }, "weight": { "type": [ "number", "null" ], "format": "float", "description": "Share of the audience, as a 0-1 fraction." } } }, "description": "Languages the audience speaks, strongest first." }, "top_ethnicities": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": [ "string", "null" ], "description": "Code identifying the ethnicity." }, "name": { "type": [ "string", "null" ], "description": "Display name of the ethnicity." }, "weight": { "type": [ "number", "null" ], "format": "float", "description": "Share of the audience, as a 0-1 fraction." } } }, "description": "Ethnicity breakdown of the audience. Instagram-only; empty otherwise." } }, "required": [ "top_countries", "top_languages", "top_ethnicities" ] } }, "required": [ "obj" ], "additionalProperties": false }, "examples": { "default": { "value": { "obj": { "source_platform": "instagram", "demographics": { "male_percent": 0.634776, "female_percent": 0.365224, "age_groups": { "13-17": 0.046817, "18-24": 0.309867, "25-34": 0.418992, "35-44": 0.160466, "45-64": 0.063359, "65+": 0.000498 } }, "top_countries": [ { "code": "US", "name": "United States", "weight": 0.733002 }, { "code": "MX", "name": "Mexico", "weight": 0.032383 } ], "top_languages": [ { "code": "en", "name": "English", "weight": 0.738099 } ], "top_ethnicities": [ { "code": "white", "name": "White", "weight": 0.51 } ] } } } } } } } } } }, "/api/brand/v2/{brandId}": { "get": { "summary": "Get Brand Info (V2)", "tags": [ "Brand" ], "operationId": "getBrandInfoV2", "description": "Brand profile — identity, categorisation, per-platform follower counts, social handles — plus the artists whose audience best matches the brand.\n\nReplaces `GET /api/brand/{brandId}`. The two do not share a brand universe, so a `brandId` from V1 is not valid here.\n\n| V1 | V2 |\n|---|---|\n| Artist list only (`brandName`, `total`, `artists`) | Full brand profile plus the artist list |\n| Instagram followers only | `instagram_followers`, `tiktok_followers`, `youtube_followers` |\n| `affinity`, a ratio around 1.0 | `audience_similarity`, a 0-100 Affinity score |\n| `overlap`, `overlap_percent`, `instagram_likers.*` | no equivalent — the affinity model was rebuilt |\n\nReturns `null` in `obj` when the brand ID is unknown.", "parameters": [ { "name": "brandId", "in": "path", "schema": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric brand ID." }, "required": true, "description": "Chartmetric brand ID.", "examples": { "default": { "value": 1 } } }, { "name": "sortColumn", "in": "query", "schema": { "type": "string", "enum": [ "followers", "name", "audienceSimilarity" ], "description": "Column used to sort the artist list. One of `followers`, `name`, `audienceSimilarity`. Defaults to `followers`.", "default": "followers" }, "required": false, "description": "Column used to sort the artist list. One of `followers`, `name`, `audienceSimilarity`. Defaults to `followers`." }, { "name": "sortOrderDesc", "in": "query", "schema": { "type": "boolean", "description": "If true (default), sort `sortColumn` in descending order.", "default": true }, "required": false, "description": "If true (default), sort `sortColumn` in descending order." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum number of artists to return. Defaults to 10, max 100.", "default": 10 }, "required": false, "description": "Maximum number of artists to return. Defaults to 10, max 100." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, "required": false, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, { "name": "platform", "in": "query", "schema": { "type": "string", "enum": [ "instagram", "tiktok", "youtube" ], "description": "Platform each artist's `followers` count is reported on, which also determines the `followers` sort order. One of `instagram`, `tiktok`, `youtube`. Defaults to `instagram`. Does not affect `audience_similarity`, which always reflects the strongest platform pair.", "default": "instagram" }, "required": false, "description": "Platform each artist's `followers` count is reported on, which also determines the `followers` sort order. One of `instagram`, `tiktok`, `youtube`. Defaults to `instagram`. Does not affect `audience_similarity`, which always reflects the strongest platform pair." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric brand ID." }, "name": { "type": [ "string", "null" ], "description": "Brand name." }, "image_url": { "type": [ "string", "null" ], "description": "Brand logo or profile image URL." }, "country": { "type": [ "string", "null" ], "description": "Country the brand is based in, as an ISO 3166-1 alpha-2 code (e.g. 'US')." }, "category": { "type": [ "string", "null" ], "description": "Primary brand category (e.g. `Music`, `Electronics & Computers`)." }, "sub_categories": { "type": "array", "items": { "type": "string" }, "description": "Finer-grained brand tags. Empty when none are assigned." }, "description": { "type": [ "string", "null" ], "description": "Short brand description." }, "instagram_followers": { "type": "integer", "minimum": 0, "description": "Followers on the brand's own Instagram account. 0 when unavailable." }, "tiktok_followers": { "type": "integer", "minimum": 0, "description": "Followers on the brand's own TikTok account. 0 when unavailable." }, "youtube_followers": { "type": "integer", "minimum": 0, "description": "Subscribers on the brand's own YouTube channel. 0 when unavailable." }, "social_links": { "type": "object", "properties": { "instagram": { "type": [ "string", "null" ], "description": "URL of the brand's Instagram account." }, "tiktok": { "type": [ "string", "null" ], "description": "URL of the brand's TikTok account." }, "youtube": { "type": [ "string", "null" ], "description": "URL of the brand's YouTube channel." } }, "description": "Links to the brand's own social accounts. Each entry is null when no account is linked on that platform." }, "artist_count": { "type": "integer", "minimum": 0, "description": "Total number of artists matched to this brand, ignoring `limit` / `offset`." }, "artists": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric artist ID." }, "name": { "type": [ "string", "null" ], "description": "Artist name." }, "image_url": { "type": [ "string", "null" ], "description": "Artist image URL." }, "country": { "type": [ "string", "null" ], "description": "Artist's home country as an ISO 3166-1 alpha-2 code (e.g. 'US')." }, "followers": { "type": "integer", "minimum": 0, "description": "Artist's followers on `platform`." }, "genres": { "type": "array", "items": { "type": "string" }, "description": "Genre names for the artist." }, "audience_similarity": { "type": [ "number", "null" ], "format": "float", "description": "Affinity between the artist and the brand, 0-100, higher is a stronger match. Always computed from the strongest platform pair, so it does not change with `platform`. Replaces V1 `affinity`, which was a ratio around 1.0 — the scales are not comparable." }, "brand_platform": { "type": [ "string", "null" ], "description": "Brand-side platform of the pair that produced `audience_similarity`." }, "best_artist_platform": { "type": [ "string", "null" ], "description": "Artist-side platform of the pair that produced `audience_similarity`." } }, "required": [ "id", "followers", "genres" ] }, "description": "Matched artists, sorted and paginated as requested." } }, "required": [ "id", "sub_categories", "instagram_followers", "tiktok_followers", "youtube_followers", "social_links", "artist_count", "artists" ] } }, "additionalProperties": false }, "examples": { "default": { "value": { "obj": { "id": 138, "name": "Apple", "image_url": "https://storage.googleapis.com/cm-brand-images/138.jpg", "country": "US", "category": "Electronics & Computers", "sub_categories": [ "Smartphones", "Computers" ], "description": "Consumer electronics and software company.", "instagram_followers": 33500000, "tiktok_followers": 2100000, "youtube_followers": 19800000, "social_links": { "instagram": "https://www.instagram.com/apple", "tiktok": "https://www.tiktok.com/@apple", "youtube": "https://www.youtube.com/@Apple" }, "artist_count": 98864, "artists": [ { "id": 74419, "name": "XXXTENTACION", "image_url": "https://rovimusic.rovicorp.com/image.jpg", "country": "US", "followers": 20578742, "genres": [ "Hip-Hop/Rap", "Pop" ], "audience_similarity": 87.4, "brand_platform": "instagram", "best_artist_platform": "instagram" } ] } } } } } } } } } }, "/api/brand/{brandId}": { "get": { "summary": "Get Brand Info (deprecated)", "tags": [ "Brand" ], "operationId": "getBrandInfo", "description": "**Deprecated — removed after 2026-10-01. Use `GET /api/brand/v2/{brandId}` instead.** Artists whose audience is interested in a brand, with Instagram follower/liker overlap and affinity. Sortable by any of `followers`, `likers`, `follower_overlap`, `liker_overlap`, `follower_affinity`, `liker_affinity`.", "parameters": [ { "name": "brandId", "in": "path", "schema": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric brand ID." }, "required": true, "description": "Chartmetric brand ID.", "examples": { "default": { "value": 1 } } }, { "name": "sortColumn", "in": "query", "schema": { "type": "string", "enum": [ "followers", "likers", "follower_overlap", "liker_overlap", "follower_affinity", "liker_affinity" ], "description": "Column used to sort artists. One of `followers`, `likers`, `follower_overlap`, `liker_overlap`, `follower_affinity`, `liker_affinity`. Defaults to `followers`.", "default": "followers" }, "required": false, "description": "Column used to sort artists. One of `followers`, `likers`, `follower_overlap`, `liker_overlap`, `follower_affinity`, `liker_affinity`. Defaults to `followers`." }, { "name": "sortOrderDesc", "in": "query", "schema": { "type": "boolean", "description": "If true (default), sort `sortColumn` in descending order.", "default": true }, "required": false, "description": "If true (default), sort `sortColumn` in descending order." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "description": "Maximum number of artists to return. Defaults to 10, max 50.", "default": 10 }, "required": false, "description": "Maximum number of artists to return. Defaults to 10, max 50." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, "required": false, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "object", "properties": { "brandName": { "type": [ "string", "null" ], "description": "Brand name." }, "total": { "type": "integer", "minimum": 0, "description": "Total number of artists with an audience interested in this brand." }, "artists": { "type": "array", "items": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "description": "Chartmetric artist ID. May be returned as a string or number." }, "code2": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB')." }, "name": { "type": [ "string", "null" ], "description": "Artist name." }, "genres": { "type": "array", "items": { "type": "string" }, "description": "Up to three smart-ordered genre names for the artist." }, "image_url": { "type": [ "string", "null" ], "description": "Artist image URL." }, "instagram_followers": { "type": "object", "properties": { "total": { "type": [ "integer", "null" ], "minimum": 0, "description": "Total Instagram followers of the artist." }, "overlap": { "type": [ "integer", "null" ], "minimum": 0, "description": "Followers of the artist whose audience is interested in this brand." }, "overlap_percent": { "type": [ "number", "null" ], "format": "float", "description": "Share of the artist's followers interested in this brand (0–1)." }, "affinity": { "type": [ "number", "null" ], "format": "float", "description": "Affinity of the artist's follower base toward the brand vs. the average artist (1.0 = average)." } }, "description": "Instagram follower overlap and affinity stats for the artist's audience." }, "instagram_likers": { "type": "object", "properties": { "average": { "type": [ "integer", "null" ], "minimum": 0, "description": "Average Instagram likes per post for the artist." }, "overlap": { "type": [ "integer", "null" ], "minimum": 0, "description": "Likers of the artist's posts whose audience is interested in this brand." }, "overlap_percent": { "type": [ "number", "null" ], "format": "float", "description": "Share of the artist's likers interested in this brand (0–1)." }, "affinity": { "type": [ "number", "null" ], "format": "float", "description": "Affinity of the artist's liker base toward the brand vs. the average artist (1.0 = average)." } }, "description": "Instagram liker overlap and affinity stats for the artist's audience." } }, "required": [ "id", "genres" ] }, "description": "Artists ranked by the requested `sortColumn`, paginated by `limit`/`offset`." } }, "required": [ "total", "artists" ] } }, "additionalProperties": false }, "examples": { "default": { "value": { "obj": { "brandName": "Apple", "total": 98864, "artists": [ { "id": "74419", "code2": "US", "name": "XXXTENTACION", "genres": [ "Hip-Hop/Rap", "Pop" ], "image_url": "https://rovimusic.rovicorp.com/image.jpg?c=yuv5C_kbffM_HzyztzV8fAJZhG49AlXxcRVo_RfD3cE=&f=4", "instagram_followers": { "total": 20578742, "overlap": 1858034, "overlap_percent": 0.09028899822933782, "affinity": 1.07031695578559 }, "instagram_likers": { "average": 29561689, "overlap": 1776398, "overlap_percent": 0.060091221445432295, "affinity": 0.9514696637904785 } } ] } } } } } } } } } }, "/api/charts/{byType}/{id}/{chartType}/cm-score": { "get": { "summary": "Get Chartmetric Score", "tags": [ "Charts" ], "operationId": "getChartsCmScore", "description": "Chartmetric Score reflects the overall trend for tracks or albums, computed from weighted chart-rank positions across countries over time. Supported `byType` values are `artist`, `track`, `album` depending on `chartType`. Supported `chartType` values are `spotify-top`, `spotify-viral`, `applemusic-genre`, `applemusic-daily`, `applemusic-albums`, `itunes`, `itunes_albums`, `shazam`. Response carries two parallel views of the score timeline: `overall` (aggregate) and `individual` (per-track/per-album).", "parameters": [ { "name": "byType", "in": "path", "schema": { "type": "string", "enum": [ "artist", "track", "album" ], "description": "Entity kind that `:id` refers to (one of `artist | track | album`); must match the chosen `chartType`." }, "required": true, "description": "Entity kind that `:id` refers to (one of `artist | track | album`); must match the chosen `chartType`.", "examples": { "default": { "value": "artist" } } }, { "name": "chartType", "in": "path", "schema": { "type": "string", "enum": [ "spotify-top", "spotify-viral", "applemusic-genre", "applemusic-daily", "applemusic-albums", "itunes", "itunes_albums", "shazam" ], "description": "Chart whose Chartmetric Score is computed. One of `spotify-top`, `spotify-viral`, `applemusic-genre`, `applemusic-daily`, `applemusic-albums`, `itunes`, `itunes_albums`, `shazam`." }, "required": true, "description": "Chart whose Chartmetric Score is computed. One of `spotify-top`, `spotify-viral`, `applemusic-genre`, `applemusic-daily`, `applemusic-albums`, `itunes`, `itunes_albums`, `shazam`.", "examples": { "default": { "value": "spotify-top" } } }, { "name": "id", "in": "path", "schema": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric ID for the entity in `:byType` (artist / track / album ID)." }, "required": true, "description": "Chartmetric ID for the entity in `:byType` (artist / track / album ID).", "examples": { "default": { "value": 1 } } }, { "name": "since", "in": "query", "schema": { "type": "string", "format": "date", "description": "Start of the score time range (ISO date, e.g. `2025-11-01`); defaults to 180 days ago.", "default": "2026-05-09" }, "required": false, "description": "Start of the score time range (ISO date, e.g. `2025-11-01`); defaults to 180 days ago." }, { "name": "until", "in": "query", "schema": { "type": "string", "format": "date", "description": "End of the score time range (ISO date, e.g. `2025-11-01`); defaults to today." }, "required": false, "description": "End of the score time range (ISO date, e.g. `2025-11-01`); defaults to today." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "object", "properties": { "overall": { "type": "array", "items": { "type": "object", "properties": { "x": { "type": [ "string", "null" ], "description": "Date for the score sample (`YYYY-MM-DD`)." }, "y": { "type": [ "number", "null" ], "format": "float", "description": "Aggregate Chartmetric Score on that date." }, "count": { "type": [ "integer", "null" ], "description": "Number of contributing chart rows aggregated into `y`." }, "details": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "trackName": { "type": [ "string", "null" ], "description": "Name of the track contributing to the score." }, "trackId": { "type": [ "integer", "null" ], "description": "Chartmetric track ID of the contributing track." }, "details": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "rank": { "type": [ "integer", "null" ], "description": "Rank held by the track in the underlying chart." }, "country": { "type": [ "string", "null" ], "description": "Country code for the chart row." }, "score": { "type": [ "number", "null" ], "format": "float", "description": "Per-row score contribution." }, "genre": { "type": [ "string", "null" ], "description": "Genre of the underlying chart." } } }, "description": "Per-country/per-genre breakdown for the contributing track." } } }, "description": "List of tracks contributing to the aggregate score on this date." } } }, "description": "Aggregate score timeline across all contributing chart rows." }, "individual": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ], "description": "Chartmetric ID for the individual entity (track / album / artist)." }, "name": { "type": [ "string", "null" ], "description": "Entity name." }, "data": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "timestp": { "type": [ "string", "null" ], "format": "date-time", "description": "Date of the per-entity score sample." }, "score": { "type": [ "number", "null" ], "format": "float", "description": "Score contribution from the entity on `timestp`." }, "rank_details": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "rank": { "type": [ "integer", "null" ], "description": "Rank held in the underlying chart." }, "country": { "type": [ "string", "null" ], "description": "Country code for the chart row." }, "score": { "type": [ "number", "null" ], "format": "float", "description": "Per-row score contribution." }, "genre": { "type": [ "string", "null" ], "description": "Genre of the underlying chart." } } }, "description": "Per-country/per-genre breakdown of the per-entity score on `timestp`." } } }, "description": "Per-entity score timeline." } } }, "description": "Per-entity score timelines, one entry per contributing track / album / artist." } }, "required": [ "overall", "individual" ] } }, "additionalProperties": false }, "examples": { "default": { "value": { "obj": { "overall": [ { "x": "2020-07-01", "y": 0.39, "count": 1, "details": [ { "trackName": "Woke Up Late (feat. Hailee Steinfeld)", "trackId": 22310714, "details": [ { "rank": 180, "country": "AU", "score": 0.39 } ] } ] } ], "individual": [ { "id": 22310714, "name": "Woke Up Late (feat. Hailee Steinfeld)", "data": [ { "timestp": "2020-07-01T00:00:00.000Z", "score": 0.39, "rank_details": [ { "rank": 180, "country": "AU", "score": 0.39 } ] } ] } ] } } } } } } } } } }, "/api/charts/spotify": { "get": { "summary": "Get Spotify Track Charts", "tags": [ "Charts" ], "operationId": "getSpotifyCharts", "description": "Return tracks charting on Spotify (Top 50, Viral 50, regional, or official-country charts) for a given date/interval. Each entry combines the chart row (`rank`, `peak_rank`, `rankStats`, etc.) with the track basic info (artists, albums, cross-platform IDs). `current_plays` and `rankStats.plays` are deprecated after 2022-06-02 and will be null for later rows.", "parameters": [ { "name": "country_code", "in": "query", "schema": { "type": "string", "minLength": 2, "maxLength": 6, "description": "ISO 3166-1 alpha-2 country code (e.g. 'US', 'BR') or 'GLOBAL' for the global chart." }, "required": true, "description": "ISO 3166-1 alpha-2 country code (e.g. 'US', 'BR') or 'GLOBAL' for the global chart.", "examples": { "default": { "value": "US" } } }, { "name": "interval", "in": "query", "schema": { "type": "string", "description": "Chart interval (e.g. `daily`, `weekly`)." }, "required": true, "description": "Chart interval (e.g. `daily`, `weekly`).", "examples": { "default": { "value": "example" } } }, { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "plays", "popularity", "playlist_count", "playlist_reach", "viral", "regional" ], "description": "Spotify track chart type (e.g. `regional`, `top200`, `viral50`, `daily_top_tracks`, `weekly_top_tracks`)." }, "required": true, "description": "Spotify track chart type (e.g. `regional`, `top200`, `viral50`, `daily_top_tracks`, `weekly_top_tracks`).", "examples": { "default": { "value": "plays" } } }, { "name": "date", "in": "query", "schema": { "anyOf": [ { "type": "string", "format": "date-time", "x-required": true } ], "description": "Date for the time-slice (YYYY-MM-DD). Required unless `latest=true`." }, "required": false, "description": "Date for the time-slice (YYYY-MM-DD). Required unless `latest=true`." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, "required": false, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, { "name": "latest", "in": "query", "schema": { "type": "boolean", "description": "If true, use the most recently available date and ignore `date`." }, "required": false, "description": "If true, use the most recently available date and ignore `date`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "object", "properties": { "length": { "type": "integer", "minimum": 0, "description": "Number of chart rows in `data`." }, "data": { "type": "array", "items": { "type": "object", "properties": { "rank": { "type": [ "integer", "null" ], "description": "Current chart position (1 = top)." }, "pre_rank": { "type": [ "integer", "null" ], "description": "Position on the previous chart period." }, "peak_rank": { "type": [ "integer", "null" ], "description": "Best (lowest-numbered) rank reached on this chart." }, "peak_date": { "type": [ "string", "null" ], "format": "date-time", "description": "Date when `peak_rank` was achieved." }, "rank_1d_change": { "type": [ "integer", "null" ], "description": "Rank change vs 1 day ago (negative = moved up)." }, "rank_7d_change": { "type": [ "integer", "null" ], "description": "Rank change vs 7 days ago (negative = moved up)." }, "chart_name": { "type": [ "string", "null" ], "description": "Human-readable chart name." }, "chart_type": { "type": [ "string", "null" ], "description": "Chart variant (e.g. `regional`, `top`, `viral`)." }, "code2": { "type": [ "string", "null" ], "description": "Chart country code (ISO 3166-1 alpha-2, or platform-specific value)." }, "timestp": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp of the chart row." }, "duration": { "type": [ "string", "null" ], "description": "Chart duration window (e.g. `daily`, `weekly`, `monthly`)." }, "added_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp the row was inserted into the chart cache." }, "velocity": { "type": [ "number", "null" ], "format": "float", "description": "Rank-velocity signal computed from rank deltas (positive = climbing)." }, "time_on_chart": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Length of time on the chart. Legacy SQL emits a duration string (e.g. `\"3 days\"`); CCC emits an integer count of periods." }, "country": { "type": [ "string", "null" ], "description": "Full country name corresponding to `code2`." }, "genre": { "type": [ "string", "null" ], "description": "Chart genre." }, "spotify": { "type": [ "integer", "null" ], "description": "Internal Spotify chart row ID." }, "itunes": { "type": [ "integer", "null" ], "description": "Internal iTunes chart row ID." }, "current_plays": { "type": [ "integer", "null" ], "minimum": 0, "description": "Stream count at chart time. Stale on Spotify charts after 2022-06-02 and may be null for later rows." }, "rankStats": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "timestp": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp at which the rank was recorded." }, "rank": { "type": [ "integer", "null" ], "description": "Rank at `timestp` (1 = top)." } } }, "description": "Per-row historical rank samples." }, "id": { "type": [ "integer", "null" ], "description": "Platform-specific row ID echoed back by the chart query (legacy)." }, "name": { "type": [ "string", "null" ], "description": "Track name." }, "isrc": { "type": [ "string", "null" ], "description": "International Standard Recording Code." }, "image_url": { "type": [ "string", "null" ], "description": "Track or album cover image URL." }, "cm_track": { "type": [ "integer", "null" ], "description": "Chartmetric track ID." }, "track_genre": { "anyOf": [ { "type": "string" }, { "type": "array", "items": {} } ], "nullable": true, "description": "Track genre(s) — string or array of strings depending on the source." }, "spotify_popularity": { "type": [ "integer", "null" ], "description": "Spotify popularity score (0–100)." }, "spotify_duration_ms": { "type": [ "integer", "null" ], "description": "Track duration on Spotify in milliseconds." }, "spotify_album_id": { "type": [ "string", "null" ], "description": "Spotify album ID associated with the track." }, "composer_name": { "type": [ "string", "null" ], "description": "Composer name(s)." }, "cm_artist": { "type": [ "array", "null" ], "items": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "description": "Chartmetric artist IDs of the track artists." }, "artist_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Track artist names." }, "code2s": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "ISO 3166-1 alpha-2 country codes per artist." }, "artist_images": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Artist profile image URLs." }, "artist_covers": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Artist cover image URLs." }, "spotify_artist_ids": { "type": [ "array", "null" ], "items": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "nullable": true }, "description": "Spotify artist IDs of the track artists." }, "spotify_artist_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Spotify artist names." }, "spotify_track_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Spotify track IDs." }, "spotify_album_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Spotify album IDs." }, "itunes_artist_ids": { "type": [ "array", "null" ], "items": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "nullable": true }, "description": "iTunes artist IDs." }, "itunes_artist_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "iTunes artist names." }, "itunes_track_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "iTunes track IDs." }, "itunes_album_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "iTunes album IDs." }, "storefronts": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Apple Music storefront codes (ISO 3166-1 alpha-2 lowercased) where the track is available." }, "album_ids": { "type": [ "array", "null" ], "items": { "type": [ "integer", "null" ] }, "description": "Chartmetric album IDs of the album(s) containing this track." }, "album_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Album names." }, "album_upc": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Album UPC (Universal Product Code) values." }, "album_label": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Record labels for the album(s)." }, "release_dates": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Album release dates." } } }, "description": "Chart rows ordered by rank (1 = highest)." } }, "required": [ "length", "data" ] } }, "additionalProperties": false }, "examples": { "default": { "value": { "obj": { "length": 1, "data": [ { "id": 4445159, "name": "What Ifs (feat. Lauren Alaina)", "isrc": "USRN11600859", "image_url": "https://i.scdn.co/image/3c29df3f40b15", "cm_track": 15711334, "rank": 1, "pre_rank": 2, "peak_rank": 1, "peak_date": "2020-06-01T00:00:00.000Z", "added_at": "2020-06-01T00:00:00.000Z", "chart_type": "regional", "chart_name": "Top Tracks", "code2": "US", "current_plays": 1084704, "time_on_chart": "3 days", "spotify": 1, "velocity": 0.25, "rankStats": [ { "rank": 1, "timestp": "2020-06-01T00:00:00.000Z", "plays": 1084704 } ], "spotify_artist_names": [ "Kane Brown", "Lauren Alaina" ], "track_genre": "contemporary country,country" } ] } } } } } } } } } }, "/api/charts/spotify/artists": { "get": { "summary": "Get Spotify Artist Charts", "tags": [ "Charts" ], "operationId": "getSpotifyArtistCharts", "description": "Return artists charting on Spotify (official daily/weekly/monthly artist charts). Each entry carries the artist basic info joined with the current chart position, streak, peak, and a short `rankStats` history. Handler strips the internal `cm_artist` field before returning.", "parameters": [ { "name": "date", "in": "query", "schema": { "anyOf": [ { "type": "string", "format": "date-time", "x-required": true } ], "description": "Date for the time-slice (YYYY-MM-DD). Required unless `latest=true`." }, "required": false, "description": "Date for the time-slice (YYYY-MM-DD). Required unless `latest=true`." }, { "name": "interval", "in": "query", "schema": { "type": "string", "enum": [ "daily", "weekly", "monthly" ], "description": "Chart interval (e.g. `daily`, `weekly`, `monthly`)." }, "required": true, "description": "Chart interval (e.g. `daily`, `weekly`, `monthly`).", "examples": { "default": { "value": "daily" } } }, { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "monthly_listeners", "popularity", "followers", "playlist_count", "playlist_reach" ], "description": "Spotify artist chart type (e.g. `top_artists`)." }, "required": true, "description": "Spotify artist chart type (e.g. `top_artists`).", "examples": { "default": { "value": "monthly_listeners" } } }, { "name": "latest", "in": "query", "schema": { "type": "boolean", "description": "If true, use the most recently available date and ignore `date`." }, "required": false, "description": "If true, use the most recently available date and ignore `date`." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, "required": false, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "object", "properties": { "length": { "type": "integer", "minimum": 0, "description": "Number of chart rows in `data`." }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ], "description": "Chartmetric artist ID." }, "name": { "type": [ "string", "null" ], "description": "Artist name." }, "image_url": { "type": [ "string", "null" ], "description": "Artist image URL." }, "isni": { "type": [ "string", "null" ], "description": "International Standard Name Identifier (ISNI)." }, "code2": { "type": [ "string", "null" ], "description": "Artist country code (ISO 3166-1 alpha-2)." }, "hometown_city": { "type": [ "string", "null" ], "description": "Artist hometown city." }, "current_city": { "type": [ "string", "null" ], "description": "Artist current city." }, "sp_followers": { "type": [ "integer", "null" ], "minimum": 0, "description": "Spotify followers count." }, "sp_popularity": { "type": [ "integer", "null" ], "description": "Spotify popularity score (0–100)." }, "sp_monthly_listeners": { "type": [ "integer", "null" ], "minimum": 0, "description": "Spotify monthly listeners count." }, "deezer_fans": { "type": [ "integer", "null" ], "minimum": 0, "description": "Deezer fans count." }, "tags": { "type": [ "array", "null" ], "items": {}, "description": "Genre tags associated with the artist." }, "spotify_artist_ids": { "type": [ "array", "null" ], "items": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "nullable": true }, "description": "Spotify artist IDs linked to this Chartmetric artist." }, "itunes_artist_ids": { "type": [ "array", "null" ], "items": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "nullable": true }, "description": "iTunes artist IDs linked to this Chartmetric artist." }, "deezer_artist_ids": { "type": [ "array", "null" ], "items": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "nullable": true }, "description": "Deezer artist IDs linked to this Chartmetric artist." }, "amazon_artist_ids": { "type": [ "array", "null" ], "items": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "nullable": true }, "description": "Amazon artist IDs linked to this Chartmetric artist." }, "cm_artist_rank": { "type": [ "integer", "null" ], "description": "Chartmetric artist rank." }, "cm_artist_score": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric artist score." }, "timestp": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp of the chart row." }, "monthly_playlist_reach": { "type": [ "integer", "null" ], "minimum": 0, "description": "Sum of follower counts across playlists containing this artist's tracks." }, "rank": { "type": [ "integer", "null" ], "description": "Current chart rank (1 = top)." }, "change": { "type": [ "integer", "null" ], "description": "Rank change from the previous interval (negative = climbed)." }, "streak": { "type": [ "integer", "null" ], "description": "Number of consecutive intervals charted." }, "peak_date": { "type": [ "string", "null" ], "format": "date-time", "description": "Date the artist achieved its peak rank." }, "peak_rank": { "type": [ "integer", "null" ], "description": "Best (lowest-numbered) rank achieved." }, "time_on_chart": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Total intervals (days/weeks/months) charted." }, "rankStats": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "date": { "type": [ "string", "null" ], "description": "Date the rank was recorded (`YYYY-MM-DD`)." }, "rank": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Rank at `date`." } } }, "description": "Historical rank samples for this artist." } } }, "description": "List of artist chart rows." } }, "required": [ "length", "data" ] } }, "additionalProperties": false }, "examples": { "default": { "value": { "obj": { "length": 1, "data": [ { "id": 123, "name": "Ariana Grande", "image_url": "https://i.scdn.co/image/abcd", "isni": null, "code2": "US", "hometown_city": "Boca Raton", "current_city": null, "sp_followers": 88000000, "sp_popularity": 95, "sp_monthly_listeners": 72000000, "deezer_fans": 1200000, "tags": [ "pop" ], "spotify_artist_ids": [ "66CXWjxzNUsdJxJ2JdwvnR" ], "itunes_artist_ids": [ "412778295" ], "deezer_artist_ids": [ "3542823" ], "amazon_artist_ids": null, "cm_artist_rank": 12, "cm_artist_score": 99.2, "timestp": "2024-05-01T00:00:00.000Z", "monthly_playlist_reach": 50000000, "rank": 1, "change": 0, "streak": 12, "peak_date": "2024-04-01T00:00:00.000Z", "peak_rank": 1, "time_on_chart": 52, "rankStats": [ { "date": "2024-05-01", "rank": "1" } ] } ] } } } } } } } } } }, "/api/charts/spotify/freshfind": { "get": { "summary": "Get Spotify Fresh Finds Charts", "tags": [ "Charts" ], "operationId": "getSpotifyFreshFindCharts", "description": "Return tracks from the Spotify Fresh Finds charts for a given date. Useful for spotting new independent-artist material. Unlike the other Spotify endpoints, the response is a bare array under `obj` (the handler does NOT wrap in `{ length, data }`).", "parameters": [ { "name": "date", "in": "query", "schema": { "anyOf": [ { "type": "string", "format": "date-time", "x-required": true } ], "description": "Date for the time-slice (YYYY-MM-DD). Required unless `latest=true`." }, "required": false, "description": "Date for the time-slice (YYYY-MM-DD). Required unless `latest=true`." }, { "name": "latest", "in": "query", "schema": { "type": "boolean", "description": "If true, use the most recently available date and ignore `date`." }, "required": false, "description": "If true, use the most recently available date and ignore `date`." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "description": "Maximum number of items to return per request.", "default": 200 }, "required": false, "description": "Maximum number of items to return per request." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, "required": false, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "array", "items": { "type": "object", "properties": { "spotify_track_id": { "type": [ "string", "null" ], "description": "Spotify track ID." }, "rank": { "type": [ "integer", "null" ], "description": "Position in the Fresh Finds chart (1 = top)." }, "num_all_playlists": { "type": [ "integer", "null" ], "minimum": 0, "description": "Total Spotify playlists currently containing this track." }, "num_ff_playlists": { "type": [ "integer", "null" ], "minimum": 0, "description": "Number of Fresh Finds playlists containing this track." }, "fresh_finds_playlists_ids": { "type": [ "array", "null" ], "items": { "type": "integer" }, "description": "Chartmetric playlist IDs of Fresh Finds playlists containing this track." }, "fresh_finds_playlists": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Names of Fresh Finds playlists containing this track." }, "artists": { "anyOf": [ { "type": "object", "properties": { "id": { "type": [ "integer", "null" ], "description": "Chartmetric artist ID." }, "name": { "type": [ "string", "null" ], "description": "Artist name." }, "code2": { "type": [ "string", "null" ], "description": "Artist country code (ISO 3166-1 alpha-2)." }, "image_url": { "type": [ "string", "null" ], "description": "Artist image URL." }, "career_health": { "type": [ "string", "null" ], "description": "Artist career trend category (e.g. `decline`, `gradual decline`, `steady`, `gradual incline`, `incline`, `breakout`)." }, "career_stage": { "type": [ "string", "null" ], "description": "Artist career stage (e.g. `undiscovered`, `developing`, `mid-level`, `mainstream`, `superstar`, `legendary`)." }, "network_strength": { "type": [ "object", "null" ], "properties": { "label": { "type": [ "string", "null" ], "description": "Overall network-strength label." }, "score": { "type": [ "number", "null" ], "format": "float", "description": "Overall normalized network-strength score (0–1)." }, "instagram_label": { "type": [ "string", "null" ], "description": "Descriptive label for Instagram performance." }, "instagram_score": { "type": [ "number", "null" ], "format": "float", "description": "Normalized Instagram network-strength score (0–1)." }, "youtube_label": { "type": [ "string", "null" ], "description": "Descriptive label for YouTube performance." }, "youtube_score": { "type": [ "number", "null" ], "format": "float", "description": "Normalized YouTube network-strength score (0–1)." } }, "description": "Per-platform network-strength signals (Instagram, YouTube, etc.)." } } }, { "type": "array", "items": { "type": "object", "properties": {} } } ], "nullable": true, "description": "Artist info for the track. May be a single object or an array depending on whether the track has multiple artists." }, "id": { "type": [ "integer", "null" ], "description": "Platform-specific row ID echoed back by the chart query (legacy)." }, "name": { "type": [ "string", "null" ], "description": "Track name." }, "isrc": { "type": [ "string", "null" ], "description": "International Standard Recording Code." }, "image_url": { "type": [ "string", "null" ], "description": "Track or album cover image URL." }, "cm_track": { "type": [ "integer", "null" ], "description": "Chartmetric track ID." }, "track_genre": { "anyOf": [ { "type": "string" }, { "type": "array", "items": {} } ], "nullable": true, "description": "Track genre(s) — string or array of strings depending on the source." }, "spotify_popularity": { "type": [ "integer", "null" ], "description": "Spotify popularity score (0–100)." }, "spotify_duration_ms": { "type": [ "integer", "null" ], "description": "Track duration on Spotify in milliseconds." }, "spotify_album_id": { "type": [ "string", "null" ], "description": "Spotify album ID associated with the track." }, "composer_name": { "type": [ "string", "null" ], "description": "Composer name(s)." }, "cm_artist": { "type": [ "array", "null" ], "items": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "description": "Chartmetric artist IDs of the track artists." }, "artist_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Track artist names." }, "code2s": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "ISO 3166-1 alpha-2 country codes per artist." }, "artist_images": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Artist profile image URLs." }, "artist_covers": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Artist cover image URLs." }, "spotify_artist_ids": { "type": [ "array", "null" ], "items": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "nullable": true }, "description": "Spotify artist IDs of the track artists." }, "spotify_artist_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Spotify artist names." }, "spotify_track_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Spotify track IDs." }, "spotify_album_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Spotify album IDs." }, "itunes_artist_ids": { "type": [ "array", "null" ], "items": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "nullable": true }, "description": "iTunes artist IDs." }, "itunes_artist_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "iTunes artist names." }, "itunes_track_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "iTunes track IDs." }, "itunes_album_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "iTunes album IDs." }, "storefronts": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Apple Music storefront codes (ISO 3166-1 alpha-2 lowercased) where the track is available." }, "album_ids": { "type": [ "array", "null" ], "items": { "type": [ "integer", "null" ] }, "description": "Chartmetric album IDs of the album(s) containing this track." }, "album_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Album names." }, "album_upc": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Album UPC (Universal Product Code) values." }, "album_label": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Record labels for the album(s)." }, "release_dates": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Album release dates." } } }, "description": "List of Fresh Finds chart rows." } }, "required": [ "obj" ], "additionalProperties": false }, "examples": { "default": { "value": { "obj": [ { "spotify_track_id": "6ocbgoVGwYJhOv1GgI9NsF", "rank": 1, "num_all_playlists": 3, "num_ff_playlists": 1, "fresh_finds_playlists_ids": [ 688460 ], "fresh_finds_playlists": [ "Fresh Finds" ], "name": "7 rings", "isrc": "USUM71900110", "image_url": "https://i.scdn.co/image/38205ab1", "cm_track": 22290726, "spotify_artist_names": [ "Ariana Grande" ], "artists": { "id": 3963, "name": "Ariana Grande", "code2": "US", "image_url": "https://i.scdn.co/image/abcd", "career_health": "Superstar", "career_stage": "Mainstream", "network_strength": { "score": 0.87, "label": "Strong", "instagram_score": 0.92, "instagram_label": "Strong", "youtube_score": 0.81, "youtube_label": "Strong" } } } ] } } } } } } } } }, "/api/charts/deezer": { "get": { "summary": "Get Deezer Top-Track Chart", "tags": [ "Charts" ], "operationId": "getDeezerCharts", "description": "Return the Deezer top-track chart for a given `country_code` and `date`. Each row merges track-basic-info (from `Track.getBasicInfoBatch`) with the chart row from `QUERY_GET_DEEZER_CHARTS` and the per-track `rankStats` history.", "parameters": [ { "name": "country_code", "in": "query", "schema": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB')." }, "required": true, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB').", "examples": { "default": { "value": "US" } } }, { "name": "date", "in": "query", "schema": { "anyOf": [ { "type": "string", "format": "date-time", "x-required": true } ], "description": "Date for the time-slice (YYYY-MM-DD). Required unless `latest=true`." }, "required": false, "description": "Date for the time-slice (YYYY-MM-DD). Required unless `latest=true`." }, { "name": "latest", "in": "query", "schema": { "type": "boolean", "description": "If true, use the most recently available date and ignore `date`." }, "required": false, "description": "If true, use the most recently available date and ignore `date`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "object", "properties": { "length": { "type": "integer", "minimum": 0, "description": "Number of chart rows in `data`." }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "nullable": true, "description": "Deezer track ID." }, "deezer": { "type": [ "integer", "null" ], "description": "Internal Deezer chart row ID." }, "deezer_album": { "anyOf": [ { "type": "object", "properties": {} }, { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Deezer album ID or album-info object." }, "deezer_artist_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Deezer artist names." }, "deezer_artist_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Deezer artist IDs." }, "deezer_track_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Deezer track IDs." }, "deezer_album_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Deezer album IDs." }, "rank": { "type": [ "integer", "null" ], "description": "Current chart rank (1 = top)." }, "added_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp the chart row was inserted." }, "code2": { "type": [ "string", "null" ], "description": "Chart country code (ISO 3166-1 alpha-2)." }, "velocity": { "type": [ "number", "null" ], "format": "float", "description": "Rank-velocity signal (positive = climbing)." }, "pre_rank": { "type": [ "integer", "null" ], "description": "Position on the previous chart period." }, "peak_rank": { "type": [ "integer", "null" ], "description": "Best (lowest-numbered) rank reached." }, "peak_date": { "type": [ "string", "null" ], "format": "date-time", "description": "Date `peak_rank` was achieved." }, "time_on_chart": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "nullable": true, "description": "Length of time on the chart (integer count of periods or duration string)." }, "rankStats": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "rank": { "type": [ "integer", "null" ], "description": "Rank at `timestp` (1 = top)." }, "timestp": { "anyOf": [ { "type": [ "string", "null" ], "format": "date-time" } ], "description": "Timestamp at which the rank was recorded." } } }, "description": "Per-row historical rank samples." }, "cm_track": { "type": [ "integer", "null" ], "description": "Chartmetric track ID." }, "name": { "type": [ "string", "null" ], "description": "Track name." }, "isrc": { "type": [ "string", "null" ], "description": "International Standard Recording Code." }, "image_url": { "type": [ "string", "null" ], "description": "Track or album cover image URL." }, "cm_artist": { "anyOf": [ { "type": "integer" }, { "type": "array", "items": { "type": [ "integer", "null" ] } } ], "nullable": true, "description": "Chartmetric artist ID(s) — single value or array depending on platform." }, "artist_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Track artist names." }, "code2s": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Country codes per artist (ISO 3166-1 alpha-2)." }, "artist_images": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Artist profile image URLs." }, "artist_covers": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Artist cover image URLs." }, "album_ids": { "type": [ "array", "null" ], "items": { "type": [ "integer", "null" ] }, "description": "Chartmetric album IDs." }, "album_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Album names." }, "album_upc": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Album UPC values." }, "album_label": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Record labels for the album(s)." }, "release_dates": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Album release dates." }, "artists": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ], "description": "Chartmetric artist ID." }, "name": { "type": [ "string", "null" ], "description": "Artist name." }, "code2": { "type": [ "string", "null" ], "description": "Artist country code (ISO 3166-1 alpha-2)." }, "image_url": { "type": [ "string", "null" ], "description": "Artist image URL." }, "career_stage": { "type": [ "string", "null" ], "description": "Artist career stage (e.g. `undiscovered`, `developing`, `mid-level`, `mainstream`, `superstar`, `legendary`)." } } }, "description": "Normalized artist info objects for the track." }, "album": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": {} } }, { "type": "object", "properties": {} } ], "nullable": true, "description": "Album info object (or array of objects) associated with the track." }, "duration_ms": { "type": [ "integer", "null" ], "description": "Track duration in milliseconds." }, "explicit": { "type": [ "boolean", "null" ], "description": "Whether the track is flagged as explicit." }, "preview_url": { "type": [ "string", "null" ], "description": "Audio preview URL." }, "track_genre": { "anyOf": [ { "type": "string" }, { "type": "array", "items": {} } ], "nullable": true, "description": "Track genre(s) — string or array of strings." }, "spotify_popularity": { "type": [ "integer", "null" ], "description": "Spotify popularity score (0–100)." } } }, "description": "Chart rows ordered by rank (1 = highest)." } }, "required": [ "length", "data" ] } }, "required": [ "obj" ] }, "examples": { "default": { "value": { "obj": { "length": 1, "data": [ { "id": "12345", "name": "Sample Track", "isrc": "USAT21906978", "image_url": "https://e-cdns-images.dzcdn.net/images/cover/abc/250x250-000000.jpg", "cm_track": 29203381, "cm_artist": [ 839964 ], "artist_names": [ "Sample Artist" ], "code2s": [ "US" ], "artist_images": [ null ], "artist_covers": [ null ], "album_ids": [ 5963064 ], "album_names": [ "Sample Album" ], "album_upc": [ "9420058747152" ], "album_label": [ "Sample Label" ], "release_dates": [ "2020-04-24T07:00:00.000Z" ], "deezer": 12345, "deezer_album": "Sample Album", "deezer_artist_names": [ "Sample Artist" ], "deezer_artist_ids": [ "5678" ], "deezer_track_ids": [ "12345" ], "deezer_album_ids": [ "910" ], "rank": 1, "added_at": "2024-05-01T00:00:00.000Z", "code2": "US", "velocity": 0, "pre_rank": 1, "peak_rank": 1, "peak_date": "2024-04-28T00:00:00.000Z", "time_on_chart": 5, "rankStats": [ { "rank": 1, "timestp": "2024-04-30T00:00:00.000Z" } ] } ] } } } } } } } } } }, "/api/charts/qq": { "get": { "summary": "QQ Music Charts", "tags": [ "Charts" ], "operationId": "getQQCharts", "description": "QQ Music top tracks chart. `QUERY_GET_QQ_CHARTS` merged with `Track.getBasicInfoBatch(\"cm\", isrcs, { isrcToggle: true })` and per-row historical `rankStats` via `QUERY_GET_TRACK_RANKINGS.QQ`.", "parameters": [ { "name": "date", "in": "query", "schema": { "anyOf": [ { "type": "string", "format": "date-time", "x-required": true } ], "description": "Date for the time-slice (YYYY-MM-DD). Required unless `latest=true`." }, "required": false, "description": "Date for the time-slice (YYYY-MM-DD). Required unless `latest=true`." }, { "name": "latest", "in": "query", "schema": { "type": "boolean", "description": "If true, use the most recently available date and ignore `date`." }, "required": false, "description": "If true, use the most recently available date and ignore `date`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "object", "properties": { "length": { "type": [ "integer", "null" ], "description": "Number of chart rows in `data`." }, "data": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 2147483647 }, { "type": "string" } ], "nullable": true, "description": "Platform-side track ID (or Chartmetric ID for ISRC-keyed lookups)." }, "name": { "type": [ "string", "null" ], "description": "Track name." }, "isrc": { "type": [ "string", "null" ], "description": "International Standard Recording Code." }, "image_url": { "type": [ "string", "null" ], "description": "Track or album cover image URL." }, "description": { "type": [ "string", "null" ], "description": "Track description (free-text metadata)." }, "tags": { "type": [ "string", "null" ], "description": "Comma-separated genre tags for the track." }, "cm_track": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Chartmetric track ID." }, "cm_artist": { "type": [ "array", "null" ], "items": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647 }, "description": "Chartmetric artist IDs of the track artists." }, "artist_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Track artist names." }, "code2s": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Country codes per artist (ISO 3166-1 alpha-2)." }, "artist_images": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Artist profile image URLs." }, "artist_covers": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Artist cover image URLs." }, "spotify_track_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Spotify track IDs." }, "spotify_album_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Spotify album IDs." }, "spotify_duration_ms": { "type": [ "integer", "null" ], "description": "Track duration on Spotify in milliseconds." }, "itunes_track_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "iTunes track IDs." }, "itunes_album_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "iTunes album IDs." }, "itunes_artist_ids": { "type": [ "array", "null" ], "items": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "nullable": true }, "description": "iTunes artist IDs." }, "itunes_artist_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "iTunes artist names." }, "storefronts": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "iTunes/Apple Music storefront codes (ISO 3166-1 alpha-2 lowercased)." }, "deezer_track_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Deezer track IDs." }, "deezer_album_ids": { "type": [ "array", "null" ], "items": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true }, "description": "Deezer album IDs." }, "deezer_duration": { "type": [ "integer", "null" ], "description": "Track duration on Deezer in seconds." }, "amazon_track_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Amazon track IDs." }, "amazon_album_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Amazon album IDs." }, "album_ids": { "type": [ "array", "null" ], "items": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 2147483647 }, { "type": "string" } ], "nullable": true }, "description": "Chartmetric album IDs." }, "album_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Album names." }, "album_upc": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Album UPC values." }, "album_label": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Record labels for the album(s)." }, "release_dates": { "type": [ "array", "null" ], "items": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string" } ], "nullable": true }, "description": "Album release dates." }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string" } ], "nullable": true, "description": "Track-record creation timestamp." }, "modified_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string" } ], "nullable": true, "description": "Track-record last-modified timestamp." }, "rank": { "type": [ "integer", "null" ], "description": "Current chart rank (1 = top)." }, "pre_rank": { "type": [ "integer", "null" ], "description": "Position on the previous chart period." }, "peak_rank": { "type": [ "integer", "null" ], "description": "Best (lowest-numbered) rank reached." }, "peak_date": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string" } ], "nullable": true, "description": "Date `peak_rank` was achieved." }, "added_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string" } ], "nullable": true, "description": "Timestamp the row was added to the chart." }, "velocity": { "type": [ "number", "null" ], "format": "float", "description": "Rank-velocity signal (positive = climbing)." }, "time_on_chart": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Length of time on the chart." }, "qq": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "QQ Music track ID." }, "rankStats": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "rank": { "type": [ "integer", "null" ], "description": "Rank at `timestp` (1 = top)." }, "timestp": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string" } ], "nullable": true, "description": "Timestamp of the rank sample." } } }, "description": "Per-row historical rank samples." } } }, "description": "Chart rows ordered by rank (1 = highest)." } } } }, "additionalProperties": false } } } } } } }, "/api/charts/amazon/tracks": { "get": { "summary": "Amazon Track Charts", "tags": [ "Charts" ], "operationId": "getAmazonTrackCharts", "description": "Amazon track charts for a country/genre/type. Data sources split by `type`: `new_track`/`popular_track` come from S3 parquet (via `#getChartsS3`), other types from the RDS `amazon_*_chart` tables. Per-row historical `rankStats` (RDS path) and merged cross-platform track metadata from `Track.getBasicInfoBatch`.", "parameters": [ { "name": "date", "in": "query", "schema": { "anyOf": [ { "type": "string", "format": "date-time", "x-required": true } ], "description": "Date for the time-slice (YYYY-MM-DD). Required unless `latest=true`." }, "required": false, "description": "Date for the time-slice (YYYY-MM-DD). Required unless `latest=true`." }, { "name": "genre", "in": "query", "schema": { "type": "string", "description": "Amazon genre filter. Use `/api/charts/genres/amazon` to retrieve the available genre IDs/names." }, "required": true, "description": "Amazon genre filter. Use `/api/charts/genres/amazon` to retrieve the available genre IDs/names.", "examples": { "default": { "value": "example" } } }, { "name": "code2", "in": "query", "schema": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB').", "default": "US" }, "required": false, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB')." }, { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "popular_track", "new_track" ], "description": "Amazon track chart type (`popular_track` or `new_track`)." }, "required": true, "description": "Amazon track chart type (`popular_track` or `new_track`).", "examples": { "default": { "value": "popular_track" } } }, { "name": "latest", "in": "query", "schema": { "type": "boolean", "description": "If true, use the most recently available date and ignore `date`." }, "required": false, "description": "If true, use the most recently available date and ignore `date`." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "description": "Maximum entries returned. Defaults to 500.", "default": 500 }, "required": false, "description": "Maximum entries returned. Defaults to 500." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, "required": false, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "object", "properties": { "length": { "type": [ "integer", "null" ], "description": "Number of chart rows in `data`." }, "data": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 2147483647 }, { "type": "string" } ], "nullable": true, "description": "Platform-side track ID (or Chartmetric ID for ISRC-keyed lookups)." }, "name": { "type": [ "string", "null" ], "description": "Track name." }, "isrc": { "type": [ "string", "null" ], "description": "International Standard Recording Code." }, "image_url": { "type": [ "string", "null" ], "description": "Track or album cover image URL." }, "description": { "type": [ "string", "null" ], "description": "Track description (free-text metadata)." }, "tags": { "type": [ "string", "null" ], "description": "Comma-separated genre tags for the track." }, "cm_track": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Chartmetric track ID." }, "cm_artist": { "type": [ "array", "null" ], "items": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647 }, "description": "Chartmetric artist IDs of the track artists." }, "artist_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Track artist names." }, "code2s": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Country codes per artist (ISO 3166-1 alpha-2)." }, "artist_images": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Artist profile image URLs." }, "artist_covers": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Artist cover image URLs." }, "spotify_track_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Spotify track IDs." }, "spotify_album_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Spotify album IDs." }, "spotify_duration_ms": { "type": [ "integer", "null" ], "description": "Track duration on Spotify in milliseconds." }, "itunes_track_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "iTunes track IDs." }, "itunes_album_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "iTunes album IDs." }, "itunes_artist_ids": { "type": [ "array", "null" ], "items": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "nullable": true }, "description": "iTunes artist IDs." }, "itunes_artist_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "iTunes artist names." }, "storefronts": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "iTunes/Apple Music storefront codes (ISO 3166-1 alpha-2 lowercased)." }, "deezer_track_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Deezer track IDs." }, "deezer_album_ids": { "type": [ "array", "null" ], "items": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true }, "description": "Deezer album IDs." }, "deezer_duration": { "type": [ "integer", "null" ], "description": "Track duration on Deezer in seconds." }, "amazon_track_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Amazon track IDs." }, "amazon_album_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Amazon album IDs." }, "album_ids": { "type": [ "array", "null" ], "items": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 2147483647 }, { "type": "string" } ], "nullable": true }, "description": "Chartmetric album IDs." }, "album_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Album names." }, "album_upc": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Album UPC values." }, "album_label": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Record labels for the album(s)." }, "release_dates": { "type": [ "array", "null" ], "items": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string" } ], "nullable": true }, "description": "Album release dates." }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string" } ], "nullable": true, "description": "Track-record creation timestamp." }, "modified_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string" } ], "nullable": true, "description": "Track-record last-modified timestamp." }, "rank_1d_change": { "type": [ "integer", "null" ], "description": "Rank change vs 1 day ago (negative = moved up)." }, "rank_7d_change": { "type": [ "integer", "null" ], "description": "Rank change vs 7 days ago (negative = moved up)." }, "chart_name": { "type": [ "string", "null" ], "description": "Human-readable chart name." }, "chart_type": { "type": [ "string", "null" ], "description": "Chart variant (e.g. `regional`, `top`, `viral`)." }, "code2": { "type": [ "string", "null" ], "description": "Chart country code (ISO 3166-1 alpha-2, or platform-specific value)." }, "timestp": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp of the chart row." }, "duration": { "type": [ "string", "null" ], "description": "Chart duration window (e.g. `daily`, `weekly`, `monthly`)." }, "rank": { "type": [ "integer", "null" ], "description": "Current chart rank (1 = top)." }, "pre_rank": { "type": [ "integer", "null" ], "description": "Position on the previous chart period." }, "peak_rank": { "type": [ "integer", "null" ], "description": "Best (lowest-numbered) rank reached." }, "peak_date": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string" } ], "nullable": true, "description": "Date `peak_rank` was achieved." }, "time_on_chart": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Length of time on the chart." }, "added_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string" } ], "nullable": true, "description": "Timestamp the row was added to the chart." }, "velocity": { "type": [ "number", "null" ], "format": "float", "description": "Rank-velocity signal (positive = climbing)." }, "amazon": { "type": [ "string", "null" ], "description": "Internal Amazon chart row ID." }, "amazon_browse": { "type": [ "string", "null" ], "description": "Amazon browse-node ID for the chart category." }, "amazon_artist_id": { "type": [ "string", "null" ], "description": "Amazon artist ID (primary)." }, "amazon_artist_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Amazon artist IDs of the track artists." }, "amazon_album_id": { "type": [ "string", "null" ], "description": "Amazon album ID." }, "amazon_genres": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Amazon genre tags for the track." }, "amazon_artist_names": { "anyOf": [ { "type": "array", "items": { "type": [ "string", "null" ] } }, { "type": "string" } ], "nullable": true, "description": "Amazon artist names (string or array)." }, "rankStats": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "rank": { "type": [ "integer", "null" ], "description": "Rank at `timestp` (1 = top)." }, "timestp": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string" } ], "nullable": true, "description": "Timestamp of the rank sample." } } }, "description": "Per-row historical rank samples." } } }, "description": "Chart rows ordered by rank (1 = highest)." } } } }, "additionalProperties": false } } } } } } }, "/api/charts/amazon/albums": { "get": { "summary": "Amazon Album Charts", "tags": [ "Charts" ], "operationId": "getAmazonAlbumCharts", "description": "Amazon album charts. Handler runs `QUERY_GET_AMAZON_ALBUM_CHARTS`, joins per-album metadata via `Album.getInfo(\"amazon\", …)` (rows without matching album info are dropped), and attaches historical `rankStats` from `QUERY_GET_ALBUM_RANKINGS.AMAZON`.", "parameters": [ { "name": "date", "in": "query", "schema": { "anyOf": [ { "type": "string", "format": "date-time", "x-required": true } ], "description": "Date for the time-slice (YYYY-MM-DD). Required unless `latest=true`." }, "required": false, "description": "Date for the time-slice (YYYY-MM-DD). Required unless `latest=true`." }, { "name": "genre", "in": "query", "schema": { "type": "string", "description": "Amazon genre filter. Use `/api/charts/genres/amazon` to retrieve the available genre IDs/names." }, "required": true, "description": "Amazon genre filter. Use `/api/charts/genres/amazon` to retrieve the available genre IDs/names.", "examples": { "default": { "value": "example" } } }, { "name": "code2", "in": "query", "schema": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB').", "default": "US" }, "required": false, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB')." }, { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "popular_album", "new_album" ], "description": "Amazon album chart type (`popular_album` or `new_album`)." }, "required": true, "description": "Amazon album chart type (`popular_album` or `new_album`).", "examples": { "default": { "value": "popular_album" } } }, { "name": "latest", "in": "query", "schema": { "type": "boolean", "description": "If true, use the most recently available date and ignore `date`." }, "required": false, "description": "If true, use the most recently available date and ignore `date`." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "description": "Maximum entries returned. Defaults to 500.", "default": 500 }, "required": false, "description": "Maximum entries returned. Defaults to 500." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, "required": false, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "object", "properties": { "length": { "type": [ "integer", "null" ], "description": "Number of chart rows in `data`." }, "data": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "rank": { "type": [ "integer", "null" ], "description": "Current chart rank (1 = top)." }, "pre_rank": { "type": [ "integer", "null" ], "description": "Position on the previous chart period." }, "peak_rank": { "type": [ "integer", "null" ], "description": "Best (lowest-numbered) rank reached." }, "peak_date": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string" } ], "nullable": true, "description": "Date `peak_rank` was achieved." }, "added_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string" } ], "nullable": true, "description": "Timestamp the row was added to the chart." }, "velocity": { "type": [ "number", "null" ], "format": "float", "description": "Rank-velocity signal (positive = climbing)." }, "time_on_chart": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Length of time on the chart." }, "amazon_album": { "anyOf": [ { "type": "string" }, { "type": "integer", "minimum": 0, "maximum": 2147483647 } ], "nullable": true, "description": "Amazon album row ID (numeric or string)." }, "original_id": { "type": [ "string", "null" ], "description": "Original platform identifier echoed from the chart row." }, "code2": { "type": [ "string", "null" ], "description": "Chart country code (ISO 3166-1 alpha-2)." }, "genre": { "type": [ "string", "null" ], "description": "Chart genre." }, "id": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 2147483647 }, { "type": "string" } ], "nullable": true, "description": "Amazon album ID (from album-info join)." }, "name": { "type": [ "string", "null" ], "description": "Album name." }, "upc": { "type": [ "string", "null" ], "description": "Universal Product Code identifying the release." }, "label": { "type": [ "string", "null" ], "description": "Record label that released the album." }, "image_url": { "type": [ "string", "null" ], "description": "Album cover image URL." }, "release_date": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string" } ], "nullable": true, "description": "Album release date." }, "cm_album": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Chartmetric album ID." }, "num_track": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Number of tracks on the album." }, "amazon_album_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Amazon album IDs." }, "artists": { "type": [ "array", "null" ], "items": { "type": "object", "properties": {} }, "description": "Artist info objects for the album." }, "rankStats": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "rank": { "type": [ "integer", "null" ], "description": "Rank at `timestp` (1 = top)." }, "timestp": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string" } ], "nullable": true, "description": "Timestamp of the rank sample." } } }, "description": "Per-row historical rank samples." } } }, "description": "Chart rows ordered by rank (1 = highest)." } } } }, "additionalProperties": false } } } } } } }, "/api/charts/applemusic/tracks": { "get": { "summary": "Get Apple Music Track Charts", "tags": [ "Charts" ], "operationId": "getAppleMusicTrackCharts", "description": "Return tracks charting on Apple Music for a given date. Supports `type` = `top` / `daily` / `city`; `city` requires `city_id`, and every other type requires `country_code`. `genre` applies to `top` only and defaults to `All Genres` — Apple Music's own un-segmented chart, ranked alongside the per-genre ones rather than combining them. Entries combine chart position + historical `rankStats` with the track basic info. The `top` S3-backed chart path applies pagination after the fetch.", "parameters": [ { "name": "date", "in": "query", "schema": { "anyOf": [ { "type": "string", "format": "date-time", "x-required": true } ], "description": "Date for the time-slice (YYYY-MM-DD). Required unless `latest=true`." }, "required": false, "description": "Date for the time-slice (YYYY-MM-DD). Required unless `latest=true`." }, { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "top", "daily", "city" ], "description": "Apple Music chart type. `genre` applies to `top` only; `city` requires `city_id` instead of `country_code`." }, "required": true, "description": "Apple Music chart type. `genre` applies to `top` only; `city` requires `city_id` instead of `country_code`.", "examples": { "default": { "value": "top" } } }, { "name": "genre", "in": "query", "schema": { "type": "string", "oneOf": [ { "type": "string", "description": "Chart genre filter. Defaults to the un-segmented 'All Genres' chart when omitted.", "default": "All Genres" } ] }, "required": false }, { "name": "city_id", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 2147483647, "oneOf": [ { "x-required": true } ], "description": "Chartmetric city ID. Required when `type=city` to scope the chart to a city." }, "required": false, "description": "Chartmetric city ID. Required when `type=city` to scope the chart to a city." }, { "name": "country_code", "in": "query", "schema": { "anyOf": [ { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB')." }, { "type": "string", "enum": [ "GLOBAL" ] } ], "oneOf": [ { "x-required": true } ], "description": "ISO 3166-1 alpha-2 country code (uppercase, e.g. 'US') or the literal 'GLOBAL' for cross-country charts." }, "required": false, "description": "ISO 3166-1 alpha-2 country code (uppercase, e.g. 'US') or the literal 'GLOBAL' for cross-country charts." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, "required": false, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, { "name": "latest", "in": "query", "schema": { "type": "boolean", "description": "If true, use the most recently available date and ignore `date`." }, "required": false, "description": "If true, use the most recently available date and ignore `date`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "object", "properties": { "length": { "type": "integer", "minimum": 0, "description": "Number of chart rows in `data`." }, "data": { "type": "array", "items": { "type": "object", "properties": { "rank": { "type": [ "integer", "null" ], "description": "Current chart position (1 = top)." }, "pre_rank": { "type": [ "integer", "null" ], "description": "Position on the previous chart period." }, "peak_rank": { "type": [ "integer", "null" ], "description": "Best (lowest-numbered) rank reached on this chart." }, "peak_date": { "type": [ "string", "null" ], "format": "date-time", "description": "Date when `peak_rank` was achieved." }, "rank_1d_change": { "type": [ "integer", "null" ], "description": "Rank change vs 1 day ago (negative = moved up)." }, "rank_7d_change": { "type": [ "integer", "null" ], "description": "Rank change vs 7 days ago (negative = moved up)." }, "chart_name": { "type": [ "string", "null" ], "description": "Human-readable chart name." }, "chart_type": { "type": [ "string", "null" ], "description": "Chart variant (e.g. `regional`, `top`, `viral`)." }, "code2": { "type": [ "string", "null" ], "description": "Chart country code (ISO 3166-1 alpha-2, or platform-specific value)." }, "timestp": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp of the chart row." }, "duration": { "type": [ "string", "null" ], "description": "Chart duration window (e.g. `daily`, `weekly`, `monthly`)." }, "added_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp the row was inserted into the chart cache." }, "velocity": { "type": [ "number", "null" ], "format": "float", "description": "Rank-velocity signal computed from rank deltas (positive = climbing)." }, "time_on_chart": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Length of time on the chart. Legacy SQL emits a duration string (e.g. `\"3 days\"`); CCC emits an integer count of periods." }, "country": { "type": [ "string", "null" ], "description": "Full country name corresponding to `code2`." }, "genre": { "type": [ "string", "null" ], "description": "Chart genre." }, "spotify": { "type": [ "integer", "null" ], "description": "Internal Spotify chart row ID." }, "itunes": { "type": [ "integer", "null" ], "description": "Internal iTunes chart row ID." }, "current_plays": { "type": [ "integer", "null" ], "minimum": 0, "description": "Stream count at chart time. Stale on Spotify charts after 2022-06-02 and may be null for later rows." }, "rankStats": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "timestp": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp at which the rank was recorded." }, "rank": { "type": [ "integer", "null" ], "description": "Rank at `timestp` (1 = top)." } } }, "description": "Per-row historical rank samples." }, "id": { "type": [ "integer", "null" ], "description": "Platform-specific row ID echoed back by the chart query (legacy)." }, "name": { "type": [ "string", "null" ], "description": "Track name." }, "isrc": { "type": [ "string", "null" ], "description": "International Standard Recording Code." }, "image_url": { "type": [ "string", "null" ], "description": "Track or album cover image URL." }, "cm_track": { "type": [ "integer", "null" ], "description": "Chartmetric track ID." }, "track_genre": { "anyOf": [ { "type": "string" }, { "type": "array", "items": {} } ], "nullable": true, "description": "Track genre(s) — string or array of strings depending on the source." }, "spotify_popularity": { "type": [ "integer", "null" ], "description": "Spotify popularity score (0–100)." }, "spotify_duration_ms": { "type": [ "integer", "null" ], "description": "Track duration on Spotify in milliseconds." }, "spotify_album_id": { "type": [ "string", "null" ], "description": "Spotify album ID associated with the track." }, "composer_name": { "type": [ "string", "null" ], "description": "Composer name(s)." }, "cm_artist": { "type": [ "array", "null" ], "items": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "description": "Chartmetric artist IDs of the track artists." }, "artist_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Track artist names." }, "code2s": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "ISO 3166-1 alpha-2 country codes per artist." }, "artist_images": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Artist profile image URLs." }, "artist_covers": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Artist cover image URLs." }, "spotify_artist_ids": { "type": [ "array", "null" ], "items": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "nullable": true }, "description": "Spotify artist IDs of the track artists." }, "spotify_artist_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Spotify artist names." }, "spotify_track_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Spotify track IDs." }, "spotify_album_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Spotify album IDs." }, "itunes_artist_ids": { "type": [ "array", "null" ], "items": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "nullable": true }, "description": "iTunes artist IDs." }, "itunes_artist_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "iTunes artist names." }, "itunes_track_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "iTunes track IDs." }, "itunes_album_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "iTunes album IDs." }, "storefronts": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Apple Music storefront codes (ISO 3166-1 alpha-2 lowercased) where the track is available." }, "album_ids": { "type": [ "array", "null" ], "items": { "type": [ "integer", "null" ] }, "description": "Chartmetric album IDs of the album(s) containing this track." }, "album_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Album names." }, "album_upc": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Album UPC (Universal Product Code) values." }, "album_label": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Record labels for the album(s)." }, "release_dates": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Album release dates." } } }, "description": "Chart rows ordered by rank (1 = highest)." } }, "required": [ "length", "data" ] } }, "additionalProperties": false }, "examples": { "default": { "value": { "obj": { "length": 1, "data": [ { "id": 15678739, "name": "Angels", "isrc": "USRC11700153", "image_url": "https://i.scdn.co/image/5026fddc", "cm_track": 15678739, "itunes": 12345, "rank": 5, "pre_rank": 7, "peak_rank": 1, "peak_date": "2024-02-01T00:00:00.000Z", "added_at": "2024-05-01T00:00:00.000Z", "chart_type": "top", "chart_name": "Top Tracks", "code2": "US", "country": "United States", "velocity": 0.1, "time_on_chart": "10 days", "rankStats": [ { "rank": 5, "timestp": "2024-05-01T00:00:00.000Z" } ], "artist_names": [ "Khalid" ], "cm_artist": [ 209693 ], "itunes_artist_ids": [ "479756766" ], "track_genre": "pop" } ] } } } } } } } } } }, "/api/charts/applemusic/albums": { "get": { "summary": "Get Apple Music Album Charts", "tags": [ "Charts" ], "operationId": "getAppleMusicAlbumCharts", "description": "Return albums charting on Apple Music for a given date. Each entry carries album metadata joined with the chart row (`rank`, `peak_rank`, `rankStats`). Per-album fields vary by storefront; unknown keys are allowed.", "parameters": [ { "name": "date", "in": "query", "schema": { "anyOf": [ { "type": "string", "format": "date-time", "x-required": true } ], "description": "Date for the time-slice (YYYY-MM-DD). Required unless `latest=true`." }, "required": false, "description": "Date for the time-slice (YYYY-MM-DD). Required unless `latest=true`." }, { "name": "latest", "in": "query", "schema": { "type": "boolean", "description": "If true, use the most recently available date and ignore `date`." }, "required": false, "description": "If true, use the most recently available date and ignore `date`." }, { "name": "country_code", "in": "query", "schema": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB')." }, "required": true, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB').", "examples": { "default": { "value": "US" } } }, { "name": "genre", "in": "query", "schema": { "type": "string", "description": "Chart genre filter. Defaults to the un-segmented 'All Genres' chart when omitted.", "default": "All Genres" }, "required": false, "description": "Chart genre filter. Defaults to the un-segmented 'All Genres' chart when omitted." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "description": "Maximum number of items to return per request.", "default": 200 }, "required": false, "description": "Maximum number of items to return per request." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, "required": false, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "object", "properties": { "length": { "type": "integer", "minimum": 0, "description": "Number of chart rows in `data`." }, "data": { "type": "array", "items": { "type": "object", "properties": { "rank": { "type": [ "integer", "null" ], "description": "Current chart position (1 = top)." }, "pre_rank": { "type": [ "integer", "null" ], "description": "Position on the previous chart period." }, "peak_rank": { "type": [ "integer", "null" ], "description": "Best (lowest-numbered) rank reached on this chart." }, "peak_date": { "type": [ "string", "null" ], "format": "date-time", "description": "Date when `peak_rank` was achieved." }, "rank_1d_change": { "type": [ "integer", "null" ], "description": "Rank change vs 1 day ago (negative = moved up)." }, "rank_7d_change": { "type": [ "integer", "null" ], "description": "Rank change vs 7 days ago (negative = moved up)." }, "chart_name": { "type": [ "string", "null" ], "description": "Human-readable chart name." }, "chart_type": { "type": [ "string", "null" ], "description": "Chart variant (e.g. `regional`, `top`, `viral`)." }, "code2": { "type": [ "string", "null" ], "description": "Chart country code (ISO 3166-1 alpha-2, or platform-specific value)." }, "timestp": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp of the chart row." }, "duration": { "type": [ "string", "null" ], "description": "Chart duration window (e.g. `daily`, `weekly`, `monthly`)." }, "id": { "type": [ "integer", "null" ], "description": "Apple Music chart row ID (legacy)." }, "name": { "type": [ "string", "null" ], "description": "Album name." }, "image_url": { "type": [ "string", "null" ], "description": "Album cover image URL." }, "upc": { "type": [ "string", "null" ], "description": "Universal Product Code identifying the release." }, "release_date": { "type": [ "string", "null" ], "format": "date-time", "description": "Album release date." }, "label": { "type": [ "string", "null" ], "description": "Record label that released the album." }, "genre": { "type": [ "string", "null" ], "description": "Album genre on Apple Music." }, "added_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp the chart row was inserted." }, "country": { "type": [ "string", "null" ], "description": "Full country name corresponding to `code2`." }, "itunes": { "type": [ "integer", "null" ], "description": "Internal iTunes album row ID." }, "itunes_album_id": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" }, { "type": "array", "items": {} } ], "nullable": true, "description": "Apple Music / iTunes album ID(s)." }, "cm_album": { "type": [ "integer", "null" ], "description": "Chartmetric album ID." }, "cm_artist": { "type": [ "array", "null" ], "items": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "description": "Chartmetric artist IDs for the album artists." }, "artist_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Album artist names." }, "itunes_artist_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "iTunes artist IDs." }, "itunes_artist_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "iTunes artist names." }, "storefronts": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Apple Music storefront codes (ISO 3166-1 alpha-2 lowercased)." }, "velocity": { "type": [ "number", "null" ], "format": "float", "description": "Rank-velocity signal (positive = climbing)." }, "time_on_chart": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Length of time on the chart (legacy duration string or integer count of periods)." }, "rankStats": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "timestp": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp at which the rank was recorded." }, "rank": { "type": [ "integer", "null" ], "description": "Rank at `timestp` (1 = top)." } } }, "description": "Per-row historical rank samples." } } }, "description": "List of album chart rows." } }, "required": [ "length", "data" ] } }, "additionalProperties": false }, "examples": { "default": { "value": { "obj": { "length": 1, "data": [ { "id": 13133047, "name": "American Teen", "image_url": "https://is5-ssl.mzstatic.com/image/thumb/Music124/v4/abcd.jpeg", "upc": "886446326146", "release_date": "2017-03-03T08:00:00.000Z", "label": "Right Hand Music Group, LLC/RCA Records", "genre": "Pop", "rank": 3, "pre_rank": 5, "peak_rank": 1, "peak_date": "2017-03-10T00:00:00.000Z", "added_at": "2024-05-01T00:00:00.000Z", "country": "United States", "code2": "US", "itunes": 1208346789, "velocity": 0.05, "time_on_chart": "45 days", "rankStats": [ { "rank": 3, "timestp": "2024-05-01T00:00:00.000Z" } ], "artist_names": [ "Khalid" ], "cm_artist": [ 209693 ] } ] } } } } } } } } } }, "/api/charts/applemusic/videos": { "get": { "summary": "Get Apple Music Video Charts", "tags": [ "Charts" ], "operationId": "getAppleMusicVideoCharts", "description": "Return music videos charting on Apple Music for a given date. Shape mirrors the Apple Music track chart but entries reference video IDs. Many legacy fields overlap with the track endpoint.", "parameters": [ { "name": "genre", "in": "query", "schema": { "type": "string", "description": "Chart genre filter. Defaults to the un-segmented 'All Genres' chart when omitted.", "default": "All Genres" }, "required": false, "description": "Chart genre filter. Defaults to the un-segmented 'All Genres' chart when omitted." }, { "name": "country_code", "in": "query", "schema": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB')." }, "required": true, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB').", "examples": { "default": { "value": "US" } } }, { "name": "date", "in": "query", "schema": { "anyOf": [ { "type": "string", "format": "date-time", "x-required": true } ], "description": "Date for the time-slice (YYYY-MM-DD). Required unless `latest=true`." }, "required": false, "description": "Date for the time-slice (YYYY-MM-DD). Required unless `latest=true`." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, "required": false, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, { "name": "latest", "in": "query", "schema": { "type": "boolean", "description": "If true, use the most recently available date and ignore `date`." }, "required": false, "description": "If true, use the most recently available date and ignore `date`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "object", "properties": { "length": { "type": "integer", "minimum": 0, "description": "Number of chart rows in `data`." }, "data": { "type": "array", "items": { "type": "object", "properties": { "rank": { "type": [ "integer", "null" ], "description": "Current chart position (1 = top)." }, "pre_rank": { "type": [ "integer", "null" ], "description": "Position on the previous chart period." }, "peak_rank": { "type": [ "integer", "null" ], "description": "Best (lowest-numbered) rank reached on this chart." }, "peak_date": { "type": [ "string", "null" ], "format": "date-time", "description": "Date when `peak_rank` was achieved." }, "rank_1d_change": { "type": [ "integer", "null" ], "description": "Rank change vs 1 day ago (negative = moved up)." }, "rank_7d_change": { "type": [ "integer", "null" ], "description": "Rank change vs 7 days ago (negative = moved up)." }, "chart_name": { "type": [ "string", "null" ], "description": "Human-readable chart name." }, "chart_type": { "type": [ "string", "null" ], "description": "Chart variant (e.g. `regional`, `top`, `viral`)." }, "code2": { "type": [ "string", "null" ], "description": "Chart country code (ISO 3166-1 alpha-2, or platform-specific value)." }, "timestp": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp of the chart row." }, "duration": { "type": [ "string", "null" ], "description": "Chart duration window (e.g. `daily`, `weekly`, `monthly`)." }, "added_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp the row was inserted into the chart cache." }, "velocity": { "type": [ "number", "null" ], "format": "float", "description": "Rank-velocity signal computed from rank deltas (positive = climbing)." }, "time_on_chart": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Length of time on the chart. Legacy SQL emits a duration string (e.g. `\"3 days\"`); CCC emits an integer count of periods." }, "country": { "type": [ "string", "null" ], "description": "Full country name corresponding to `code2`." }, "genre": { "type": [ "string", "null" ], "description": "Chart genre." }, "spotify": { "type": [ "integer", "null" ], "description": "Internal Spotify chart row ID." }, "itunes": { "type": [ "integer", "null" ], "description": "Internal iTunes chart row ID." }, "current_plays": { "type": [ "integer", "null" ], "minimum": 0, "description": "Stream count at chart time. Stale on Spotify charts after 2022-06-02 and may be null for later rows." }, "rankStats": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "timestp": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp at which the rank was recorded." }, "rank": { "type": [ "integer", "null" ], "description": "Rank at `timestp` (1 = top)." } } }, "description": "Per-row historical rank samples." }, "id": { "type": [ "integer", "null" ], "description": "Platform-specific row ID echoed back by the chart query (legacy)." }, "name": { "type": [ "string", "null" ], "description": "Track name." }, "isrc": { "type": [ "string", "null" ], "description": "International Standard Recording Code." }, "image_url": { "type": [ "string", "null" ], "description": "Track or album cover image URL." }, "cm_track": { "type": [ "integer", "null" ], "description": "Chartmetric track ID." }, "track_genre": { "anyOf": [ { "type": "string" }, { "type": "array", "items": {} } ], "nullable": true, "description": "Track genre(s) — string or array of strings depending on the source." }, "spotify_popularity": { "type": [ "integer", "null" ], "description": "Spotify popularity score (0–100)." }, "spotify_duration_ms": { "type": [ "integer", "null" ], "description": "Track duration on Spotify in milliseconds." }, "spotify_album_id": { "type": [ "string", "null" ], "description": "Spotify album ID associated with the track." }, "composer_name": { "type": [ "string", "null" ], "description": "Composer name(s)." }, "cm_artist": { "type": [ "array", "null" ], "items": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "description": "Chartmetric artist IDs of the track artists." }, "artist_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Track artist names." }, "code2s": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "ISO 3166-1 alpha-2 country codes per artist." }, "artist_images": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Artist profile image URLs." }, "artist_covers": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Artist cover image URLs." }, "spotify_artist_ids": { "type": [ "array", "null" ], "items": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "nullable": true }, "description": "Spotify artist IDs of the track artists." }, "spotify_artist_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Spotify artist names." }, "spotify_track_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Spotify track IDs." }, "spotify_album_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Spotify album IDs." }, "itunes_artist_ids": { "type": [ "array", "null" ], "items": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "nullable": true }, "description": "iTunes artist IDs." }, "itunes_artist_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "iTunes artist names." }, "itunes_track_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "iTunes track IDs." }, "itunes_album_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "iTunes album IDs." }, "storefronts": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Apple Music storefront codes (ISO 3166-1 alpha-2 lowercased) where the track is available." }, "album_ids": { "type": [ "array", "null" ], "items": { "type": [ "integer", "null" ] }, "description": "Chartmetric album IDs of the album(s) containing this track." }, "album_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Album names." }, "album_upc": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Album UPC (Universal Product Code) values." }, "album_label": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Record labels for the album(s)." }, "release_dates": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Album release dates." } } }, "description": "Chart rows ordered by rank (1 = highest)." } }, "required": [ "length", "data" ] } }, "additionalProperties": false }, "examples": { "default": { "value": { "obj": { "length": 1, "data": [ { "id": 987654, "name": "Blinding Lights (Official Music Video)", "isrc": "USUG11904206", "image_url": "https://is5-ssl.mzstatic.com/image/thumb/Music124/v4/video.jpeg", "cm_track": 22233344, "itunes": 1487050828, "rank": 2, "pre_rank": 3, "peak_rank": 1, "peak_date": "2020-05-01T00:00:00.000Z", "added_at": "2024-05-01T00:00:00.000Z", "chart_type": "videos", "chart_name": "Top Music Videos", "code2": "US", "country": "United States", "velocity": 0.02, "time_on_chart": "120 days", "rankStats": [ { "rank": 2, "timestp": "2024-05-01T00:00:00.000Z" } ], "artist_names": [ "The Weeknd" ], "cm_artist": [ 4315 ] } ] } } } } } } } } } }, "/api/charts/itunes/tracks": { "get": { "summary": "Get iTunes Track Charts", "tags": [ "Charts" ], "operationId": "getItunesTrackCharts", "description": "Return tracks charting on iTunes for a given date, filterable by country and genre. Shape matches the Apple Music track chart — legacy per-platform SQL + basic-info join.", "parameters": [ { "name": "genre", "in": "query", "schema": { "type": "string", "description": "Chart genre filter. Defaults to the un-segmented 'All Genres' chart when omitted.", "default": "All Genres" }, "required": false, "description": "Chart genre filter. Defaults to the un-segmented 'All Genres' chart when omitted." }, { "name": "country_code", "in": "query", "schema": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB')." }, "required": true, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB').", "examples": { "default": { "value": "US" } } }, { "name": "date", "in": "query", "schema": { "anyOf": [ { "type": "string", "format": "date-time", "x-required": true } ], "description": "Date for the time-slice (YYYY-MM-DD). Required unless `latest=true`." }, "required": false, "description": "Date for the time-slice (YYYY-MM-DD). Required unless `latest=true`." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, "required": false, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, { "name": "latest", "in": "query", "schema": { "type": "boolean", "description": "If true, use the most recently available date and ignore `date`." }, "required": false, "description": "If true, use the most recently available date and ignore `date`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "object", "properties": { "length": { "type": "integer", "minimum": 0, "description": "Number of chart rows in `data`." }, "data": { "type": "array", "items": { "type": "object", "properties": { "rank": { "type": [ "integer", "null" ], "description": "Current chart position (1 = top)." }, "pre_rank": { "type": [ "integer", "null" ], "description": "Position on the previous chart period." }, "peak_rank": { "type": [ "integer", "null" ], "description": "Best (lowest-numbered) rank reached on this chart." }, "peak_date": { "type": [ "string", "null" ], "format": "date-time", "description": "Date when `peak_rank` was achieved." }, "rank_1d_change": { "type": [ "integer", "null" ], "description": "Rank change vs 1 day ago (negative = moved up)." }, "rank_7d_change": { "type": [ "integer", "null" ], "description": "Rank change vs 7 days ago (negative = moved up)." }, "chart_name": { "type": [ "string", "null" ], "description": "Human-readable chart name." }, "chart_type": { "type": [ "string", "null" ], "description": "Chart variant (e.g. `regional`, `top`, `viral`)." }, "code2": { "type": [ "string", "null" ], "description": "Chart country code (ISO 3166-1 alpha-2, or platform-specific value)." }, "timestp": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp of the chart row." }, "duration": { "type": [ "string", "null" ], "description": "Chart duration window (e.g. `daily`, `weekly`, `monthly`)." }, "added_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp the row was inserted into the chart cache." }, "velocity": { "type": [ "number", "null" ], "format": "float", "description": "Rank-velocity signal computed from rank deltas (positive = climbing)." }, "time_on_chart": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Length of time on the chart. Legacy SQL emits a duration string (e.g. `\"3 days\"`); CCC emits an integer count of periods." }, "country": { "type": [ "string", "null" ], "description": "Full country name corresponding to `code2`." }, "genre": { "type": [ "string", "null" ], "description": "Chart genre." }, "spotify": { "type": [ "integer", "null" ], "description": "Internal Spotify chart row ID." }, "itunes": { "type": [ "integer", "null" ], "description": "Internal iTunes chart row ID." }, "current_plays": { "type": [ "integer", "null" ], "minimum": 0, "description": "Stream count at chart time. Stale on Spotify charts after 2022-06-02 and may be null for later rows." }, "rankStats": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "timestp": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp at which the rank was recorded." }, "rank": { "type": [ "integer", "null" ], "description": "Rank at `timestp` (1 = top)." } } }, "description": "Per-row historical rank samples." }, "id": { "type": [ "integer", "null" ], "description": "Platform-specific row ID echoed back by the chart query (legacy)." }, "name": { "type": [ "string", "null" ], "description": "Track name." }, "isrc": { "type": [ "string", "null" ], "description": "International Standard Recording Code." }, "image_url": { "type": [ "string", "null" ], "description": "Track or album cover image URL." }, "cm_track": { "type": [ "integer", "null" ], "description": "Chartmetric track ID." }, "track_genre": { "anyOf": [ { "type": "string" }, { "type": "array", "items": {} } ], "nullable": true, "description": "Track genre(s) — string or array of strings depending on the source." }, "spotify_popularity": { "type": [ "integer", "null" ], "description": "Spotify popularity score (0–100)." }, "spotify_duration_ms": { "type": [ "integer", "null" ], "description": "Track duration on Spotify in milliseconds." }, "spotify_album_id": { "type": [ "string", "null" ], "description": "Spotify album ID associated with the track." }, "composer_name": { "type": [ "string", "null" ], "description": "Composer name(s)." }, "cm_artist": { "type": [ "array", "null" ], "items": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "description": "Chartmetric artist IDs of the track artists." }, "artist_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Track artist names." }, "code2s": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "ISO 3166-1 alpha-2 country codes per artist." }, "artist_images": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Artist profile image URLs." }, "artist_covers": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Artist cover image URLs." }, "spotify_artist_ids": { "type": [ "array", "null" ], "items": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "nullable": true }, "description": "Spotify artist IDs of the track artists." }, "spotify_artist_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Spotify artist names." }, "spotify_track_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Spotify track IDs." }, "spotify_album_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Spotify album IDs." }, "itunes_artist_ids": { "type": [ "array", "null" ], "items": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "nullable": true }, "description": "iTunes artist IDs." }, "itunes_artist_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "iTunes artist names." }, "itunes_track_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "iTunes track IDs." }, "itunes_album_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "iTunes album IDs." }, "storefronts": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Apple Music storefront codes (ISO 3166-1 alpha-2 lowercased) where the track is available." }, "album_ids": { "type": [ "array", "null" ], "items": { "type": [ "integer", "null" ] }, "description": "Chartmetric album IDs of the album(s) containing this track." }, "album_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Album names." }, "album_upc": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Album UPC (Universal Product Code) values." }, "album_label": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Record labels for the album(s)." }, "release_dates": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Album release dates." } } }, "description": "Chart rows ordered by rank (1 = highest)." } }, "required": [ "length", "data" ] } }, "additionalProperties": false }, "examples": { "default": { "value": { "obj": { "length": 1, "data": [ { "id": 22290726, "name": "7 rings", "isrc": "USUM71900110", "image_url": "https://is5-ssl.mzstatic.com/image/thumb/Music114/v4/7rings.jpeg", "cm_track": 22290726, "itunes": 1449156176, "rank": 4, "pre_rank": 6, "peak_rank": 1, "peak_date": "2019-02-08T08:00:00.000Z", "added_at": "2024-05-01T00:00:00.000Z", "genre": "Pop", "code2": "US", "velocity": 0.08, "time_on_chart": "200 days", "rankStats": [ { "rank": 4, "timestp": "2024-05-01T00:00:00.000Z" } ], "artist_names": [ "Ariana Grande" ], "cm_artist": [ 3963 ] } ] } } } } } } } } } }, "/api/charts/itunes/albums": { "get": { "summary": "Get iTunes Album Charts", "tags": [ "Charts" ], "operationId": "getItunesAlbumCharts", "description": "Return albums charting on iTunes for a given date, filterable by country and genre. Entries carry album metadata + chart position + `rankStats`.", "parameters": [ { "name": "genre", "in": "query", "schema": { "type": "string", "description": "Chart genre filter. Defaults to the un-segmented 'All Genres' chart when omitted.", "default": "All Genres" }, "required": false, "description": "Chart genre filter. Defaults to the un-segmented 'All Genres' chart when omitted." }, { "name": "country_code", "in": "query", "schema": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB')." }, "required": true, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB').", "examples": { "default": { "value": "US" } } }, { "name": "date", "in": "query", "schema": { "anyOf": [ { "type": "string", "format": "date-time", "x-required": true } ], "description": "Date for the time-slice (YYYY-MM-DD). Required unless `latest=true`." }, "required": false, "description": "Date for the time-slice (YYYY-MM-DD). Required unless `latest=true`." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, "required": false, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, { "name": "latest", "in": "query", "schema": { "type": "boolean", "description": "If true, use the most recently available date and ignore `date`." }, "required": false, "description": "If true, use the most recently available date and ignore `date`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "object", "properties": { "length": { "type": "integer", "minimum": 0, "description": "Number of chart rows in `data`." }, "data": { "type": "array", "items": { "type": "object", "properties": { "rank": { "type": [ "integer", "null" ], "description": "Current chart position (1 = top)." }, "pre_rank": { "type": [ "integer", "null" ], "description": "Position on the previous chart period." }, "peak_rank": { "type": [ "integer", "null" ], "description": "Best (lowest-numbered) rank reached on this chart." }, "peak_date": { "type": [ "string", "null" ], "format": "date-time", "description": "Date when `peak_rank` was achieved." }, "rank_1d_change": { "type": [ "integer", "null" ], "description": "Rank change vs 1 day ago (negative = moved up)." }, "rank_7d_change": { "type": [ "integer", "null" ], "description": "Rank change vs 7 days ago (negative = moved up)." }, "chart_name": { "type": [ "string", "null" ], "description": "Human-readable chart name." }, "chart_type": { "type": [ "string", "null" ], "description": "Chart variant (e.g. `regional`, `top`, `viral`)." }, "code2": { "type": [ "string", "null" ], "description": "Chart country code (ISO 3166-1 alpha-2, or platform-specific value)." }, "timestp": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp of the chart row." }, "duration": { "type": [ "string", "null" ], "description": "Chart duration window (e.g. `daily`, `weekly`, `monthly`)." }, "id": { "type": [ "integer", "null" ], "description": "iTunes chart row ID (legacy)." }, "name": { "type": [ "string", "null" ], "description": "Album name." }, "image_url": { "type": [ "string", "null" ], "description": "Album cover image URL." }, "upc": { "type": [ "string", "null" ], "description": "Universal Product Code identifying the release." }, "release_date": { "type": [ "string", "null" ], "format": "date-time", "description": "Album release date." }, "label": { "type": [ "string", "null" ], "description": "Record label that released the album." }, "genre": { "type": [ "string", "null" ], "description": "Album genre on iTunes." }, "added_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp the chart row was inserted." }, "country": { "type": [ "string", "null" ], "description": "Full country name corresponding to `code2`." }, "itunes": { "type": [ "integer", "null" ], "description": "Internal iTunes album row ID." }, "itunes_album_id": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" }, { "type": "array", "items": {} } ], "nullable": true, "description": "iTunes album ID(s)." }, "cm_album": { "type": [ "integer", "null" ], "description": "Chartmetric album ID." }, "cm_artist": { "type": [ "array", "null" ], "items": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "description": "Chartmetric artist IDs for the album artists." }, "artist_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Album artist names." }, "itunes_artist_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "iTunes artist IDs." }, "itunes_artist_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "iTunes artist names." }, "storefronts": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "iTunes storefront codes (ISO 3166-1 alpha-2 lowercased)." }, "velocity": { "type": [ "number", "null" ], "format": "float", "description": "Rank-velocity signal (positive = climbing)." }, "time_on_chart": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Length of time on the chart (legacy duration string or integer count of periods)." }, "rankStats": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "timestp": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp at which the rank was recorded." }, "rank": { "type": [ "integer", "null" ], "description": "Rank at `timestp` (1 = top)." } } }, "description": "Per-row historical rank samples." } } }, "description": "List of album chart rows." } }, "required": [ "length", "data" ] } }, "additionalProperties": false }, "examples": { "default": { "value": { "obj": { "length": 1, "data": [ { "id": 13133047, "name": "American Teen", "image_url": "https://is5-ssl.mzstatic.com/image/thumb/Music124/v4/at.jpeg", "upc": "886446326146", "release_date": "2017-03-03T08:00:00.000Z", "label": "Right Hand Music Group, LLC/RCA Records", "genre": "Pop", "rank": 10, "pre_rank": 9, "peak_rank": 1, "peak_date": "2017-03-10T00:00:00.000Z", "added_at": "2024-05-01T00:00:00.000Z", "country": "United States", "code2": "US", "itunes": 1208346789, "velocity": -0.03, "time_on_chart": "2000 days", "rankStats": [ { "rank": 10, "timestp": "2024-05-01T00:00:00.000Z" } ], "artist_names": [ "Khalid" ], "cm_artist": [ 209693 ] } ] } } } } } } } } } }, "/api/charts/itunes/videos": { "get": { "summary": "Get iTunes Video Charts", "tags": [ "Charts" ], "operationId": "getItunesVideoCharts", "description": "Return music videos charting on iTunes for a given date. Genre is fixed to `Music Videos` by the handler. Shape mirrors the iTunes track chart.", "parameters": [ { "name": "country_code", "in": "query", "schema": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB')." }, "required": true, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB').", "examples": { "default": { "value": "US" } } }, { "name": "date", "in": "query", "schema": { "anyOf": [ { "type": "string", "format": "date-time", "x-required": true } ], "description": "Date for the time-slice (YYYY-MM-DD). Required unless `latest=true`." }, "required": false, "description": "Date for the time-slice (YYYY-MM-DD). Required unless `latest=true`." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, "required": false, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, { "name": "latest", "in": "query", "schema": { "type": "boolean", "description": "If true, use the most recently available date and ignore `date`." }, "required": false, "description": "If true, use the most recently available date and ignore `date`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "object", "properties": { "length": { "type": "integer", "minimum": 0, "description": "Number of chart rows in `data`." }, "data": { "type": "array", "items": { "type": "object", "properties": { "rank": { "type": [ "integer", "null" ], "description": "Current chart position (1 = top)." }, "pre_rank": { "type": [ "integer", "null" ], "description": "Position on the previous chart period." }, "peak_rank": { "type": [ "integer", "null" ], "description": "Best (lowest-numbered) rank reached on this chart." }, "peak_date": { "type": [ "string", "null" ], "format": "date-time", "description": "Date when `peak_rank` was achieved." }, "rank_1d_change": { "type": [ "integer", "null" ], "description": "Rank change vs 1 day ago (negative = moved up)." }, "rank_7d_change": { "type": [ "integer", "null" ], "description": "Rank change vs 7 days ago (negative = moved up)." }, "chart_name": { "type": [ "string", "null" ], "description": "Human-readable chart name." }, "chart_type": { "type": [ "string", "null" ], "description": "Chart variant (e.g. `regional`, `top`, `viral`)." }, "code2": { "type": [ "string", "null" ], "description": "Chart country code (ISO 3166-1 alpha-2, or platform-specific value)." }, "timestp": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp of the chart row." }, "duration": { "type": [ "string", "null" ], "description": "Chart duration window (e.g. `daily`, `weekly`, `monthly`)." }, "added_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp the row was inserted into the chart cache." }, "velocity": { "type": [ "number", "null" ], "format": "float", "description": "Rank-velocity signal computed from rank deltas (positive = climbing)." }, "time_on_chart": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Length of time on the chart. Legacy SQL emits a duration string (e.g. `\"3 days\"`); CCC emits an integer count of periods." }, "country": { "type": [ "string", "null" ], "description": "Full country name corresponding to `code2`." }, "genre": { "type": [ "string", "null" ], "description": "Chart genre." }, "spotify": { "type": [ "integer", "null" ], "description": "Internal Spotify chart row ID." }, "itunes": { "type": [ "integer", "null" ], "description": "Internal iTunes chart row ID." }, "current_plays": { "type": [ "integer", "null" ], "minimum": 0, "description": "Stream count at chart time. Stale on Spotify charts after 2022-06-02 and may be null for later rows." }, "rankStats": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "timestp": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp at which the rank was recorded." }, "rank": { "type": [ "integer", "null" ], "description": "Rank at `timestp` (1 = top)." } } }, "description": "Per-row historical rank samples." }, "id": { "type": [ "integer", "null" ], "description": "Platform-specific row ID echoed back by the chart query (legacy)." }, "name": { "type": [ "string", "null" ], "description": "Track name." }, "isrc": { "type": [ "string", "null" ], "description": "International Standard Recording Code." }, "image_url": { "type": [ "string", "null" ], "description": "Track or album cover image URL." }, "cm_track": { "type": [ "integer", "null" ], "description": "Chartmetric track ID." }, "track_genre": { "anyOf": [ { "type": "string" }, { "type": "array", "items": {} } ], "nullable": true, "description": "Track genre(s) — string or array of strings depending on the source." }, "spotify_popularity": { "type": [ "integer", "null" ], "description": "Spotify popularity score (0–100)." }, "spotify_duration_ms": { "type": [ "integer", "null" ], "description": "Track duration on Spotify in milliseconds." }, "spotify_album_id": { "type": [ "string", "null" ], "description": "Spotify album ID associated with the track." }, "composer_name": { "type": [ "string", "null" ], "description": "Composer name(s)." }, "cm_artist": { "type": [ "array", "null" ], "items": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "description": "Chartmetric artist IDs of the track artists." }, "artist_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Track artist names." }, "code2s": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "ISO 3166-1 alpha-2 country codes per artist." }, "artist_images": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Artist profile image URLs." }, "artist_covers": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Artist cover image URLs." }, "spotify_artist_ids": { "type": [ "array", "null" ], "items": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "nullable": true }, "description": "Spotify artist IDs of the track artists." }, "spotify_artist_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Spotify artist names." }, "spotify_track_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Spotify track IDs." }, "spotify_album_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Spotify album IDs." }, "itunes_artist_ids": { "type": [ "array", "null" ], "items": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "nullable": true }, "description": "iTunes artist IDs." }, "itunes_artist_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "iTunes artist names." }, "itunes_track_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "iTunes track IDs." }, "itunes_album_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "iTunes album IDs." }, "storefronts": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Apple Music storefront codes (ISO 3166-1 alpha-2 lowercased) where the track is available." }, "album_ids": { "type": [ "array", "null" ], "items": { "type": [ "integer", "null" ] }, "description": "Chartmetric album IDs of the album(s) containing this track." }, "album_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Album names." }, "album_upc": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Album UPC (Universal Product Code) values." }, "album_label": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Record labels for the album(s)." }, "release_dates": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Album release dates." } } }, "description": "Chart rows ordered by rank (1 = highest)." } }, "required": [ "length", "data" ] } }, "additionalProperties": false }, "examples": { "default": { "value": { "obj": { "length": 1, "data": [ { "id": 314159, "name": "Bad Guy (Official Music Video)", "isrc": "USUM71900764", "image_url": "https://is5-ssl.mzstatic.com/image/thumb/Music124/v4/bg.jpeg", "cm_track": 22001122, "itunes": 1456780213, "rank": 6, "pre_rank": 5, "peak_rank": 1, "peak_date": "2019-04-01T00:00:00.000Z", "added_at": "2024-05-01T00:00:00.000Z", "genre": "Music Videos", "code2": "US", "velocity": 0.01, "time_on_chart": "1800 days", "rankStats": [ { "rank": 6, "timestp": "2024-05-01T00:00:00.000Z" } ], "artist_names": [ "Billie Eilish" ], "cm_artist": [ 214456 ] } ] } } } } } } } } } }, "/api/charts/shazam": { "get": { "summary": "Shazam Track Charts", "tags": [ "Charts" ], "operationId": "getShazamCharts", "description": "Shazam track charts with country/city/genre filters. Handler switches between the city-level and genre-level SQL queries, then merges iTunes-linked track metadata and a `countries_charting_count` derived from a global ranking map.", "parameters": [ { "name": "country_code", "in": "query", "schema": { "anyOf": [ { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB')." }, { "type": "string", "enum": [ "GLOBAL" ] } ], "description": "ISO 3166-1 alpha-2 country code (uppercase, e.g. 'US') or the literal 'GLOBAL' for cross-country charts." }, "required": true, "description": "ISO 3166-1 alpha-2 country code (uppercase, e.g. 'US') or the literal 'GLOBAL' for cross-country charts.", "examples": { "default": { "value": "US" } } }, { "name": "date", "in": "query", "schema": { "anyOf": [ { "type": "string", "format": "date-time", "x-required": true } ], "description": "Date for the time-slice (YYYY-MM-DD). Required unless `latest=true`." }, "required": false, "description": "Date for the time-slice (YYYY-MM-DD). Required unless `latest=true`." }, { "name": "city", "in": "query", "schema": { "type": "string", "description": "Shazam chart city. May return no results when `country_code=GLOBAL`. Use `/api/charts/shazam/{country_code}/cities` to list valid cities." }, "required": false, "description": "Shazam chart city. May return no results when `country_code=GLOBAL`. Use `/api/charts/shazam/{country_code}/cities` to list valid cities." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, "required": false, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, { "name": "latest", "in": "query", "schema": { "type": "boolean", "description": "If true, use the most recently available date and ignore `date`." }, "required": false, "description": "If true, use the most recently available date and ignore `date`." }, { "name": "genre", "in": "query", "schema": { "type": "string", "enum": [ "alternative", "rock", "french-pop", "film-tv-and-stage", "randb-soul", "latin", "reggae-dancehall", "k-pop", "hip-hop-rap", "worldwide", "singer-songwriter", "dance", "afrobeats", "house", "electronic", "pop", "country", "regional-mexicano" ], "description": "Shazam genre filter; if omitted, returns chart for all genres." }, "required": false, "description": "Shazam genre filter; if omitted, returns chart for all genres." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "object", "properties": { "length": { "type": [ "integer", "null" ], "description": "Number of chart rows in `data`." }, "data": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 2147483647 }, { "type": "string" } ], "nullable": true, "description": "Platform-side track ID (or Chartmetric ID for ISRC-keyed lookups)." }, "name": { "type": [ "string", "null" ], "description": "Track name." }, "isrc": { "type": [ "string", "null" ], "description": "International Standard Recording Code." }, "image_url": { "type": [ "string", "null" ], "description": "Track or album cover image URL." }, "description": { "type": [ "string", "null" ], "description": "Track description (free-text metadata)." }, "tags": { "type": [ "string", "null" ], "description": "Comma-separated genre tags for the track." }, "cm_track": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Chartmetric track ID." }, "cm_artist": { "type": [ "array", "null" ], "items": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647 }, "description": "Chartmetric artist IDs of the track artists." }, "artist_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Track artist names." }, "code2s": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Country codes per artist (ISO 3166-1 alpha-2)." }, "artist_images": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Artist profile image URLs." }, "artist_covers": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Artist cover image URLs." }, "spotify_track_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Spotify track IDs." }, "spotify_album_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Spotify album IDs." }, "spotify_duration_ms": { "type": [ "integer", "null" ], "description": "Track duration on Spotify in milliseconds." }, "itunes_track_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "iTunes track IDs." }, "itunes_album_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "iTunes album IDs." }, "itunes_artist_ids": { "type": [ "array", "null" ], "items": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "nullable": true }, "description": "iTunes artist IDs." }, "itunes_artist_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "iTunes artist names." }, "storefronts": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "iTunes/Apple Music storefront codes (ISO 3166-1 alpha-2 lowercased)." }, "deezer_track_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Deezer track IDs." }, "deezer_album_ids": { "type": [ "array", "null" ], "items": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true }, "description": "Deezer album IDs." }, "deezer_duration": { "type": [ "integer", "null" ], "description": "Track duration on Deezer in seconds." }, "amazon_track_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Amazon track IDs." }, "amazon_album_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Amazon album IDs." }, "album_ids": { "type": [ "array", "null" ], "items": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 2147483647 }, { "type": "string" } ], "nullable": true }, "description": "Chartmetric album IDs." }, "album_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Album names." }, "album_upc": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Album UPC values." }, "album_label": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Record labels for the album(s)." }, "release_dates": { "type": [ "array", "null" ], "items": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string" } ], "nullable": true }, "description": "Album release dates." }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string" } ], "nullable": true, "description": "Track-record creation timestamp." }, "modified_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string" } ], "nullable": true, "description": "Track-record last-modified timestamp." }, "rank": { "type": [ "integer", "null" ], "description": "Current chart rank (1 = top)." }, "pre_rank": { "type": [ "integer", "null" ], "description": "Position on the previous chart period." }, "peak_rank": { "type": [ "integer", "null" ], "description": "Best (lowest-numbered) rank reached." }, "peak_date": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string" } ], "nullable": true, "description": "Date `peak_rank` was achieved." }, "added_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string" } ], "nullable": true, "description": "Timestamp the row was added to the chart." }, "velocity": { "type": [ "number", "null" ], "format": "float", "description": "Rank-velocity signal (positive = climbing)." }, "time_on_chart": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Length of time on the chart." }, "code2": { "type": [ "string", "null" ], "description": "Chart country code (ISO 3166-1 alpha-2)." }, "city": { "type": [ "string", "null" ], "description": "Chart city name (when chart is city-scoped)." }, "genre": { "type": [ "string", "null" ], "description": "Chart genre filter applied to the row." }, "shazam_track_id": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Shazam track ID. Deprecated by Shazam and no longer populated after January 2024." }, "itunes_id": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "iTunes ID for the track linked to this Shazam row." }, "itunes_track_id": { "type": [ "string", "null" ], "description": "iTunes track ID (string from track basic info)." }, "itunes_album_id": { "anyOf": [ { "type": "array", "items": { "type": [ "string", "null" ] } }, { "type": [ "string", "null" ] } ], "nullable": true, "description": "iTunes album ID(s) for the track." }, "num_of_shazams": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Total Shazam tag count for the track." }, "countries_charting_count": { "type": [ "integer", "null" ], "description": "Number of countries on which this track is currently charting on Shazam." }, "rankStats": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "rank": { "type": [ "integer", "null" ], "description": "Rank at `timestp` (1 = top)." }, "timestp": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string" } ], "nullable": true, "description": "Timestamp of the rank sample." } } }, "description": "Per-row historical rank samples." } } }, "description": "Chart rows ordered by rank (1 = highest)." } } } }, "additionalProperties": false } } } } } } }, "/api/charts/shazam/{country_code}/cities": { "get": { "summary": "Shazam Chart Cities", "tags": [ "Charts" ], "operationId": "listShazamChartCities", "description": "List of cities available for Shazam city-level filtering in a given country. Returns `cities: string[]` on success. When the country has no rows the handler returns `length: -1` and `cities: \"Invalid Country or No Cities Found\"` (legacy string fallback).", "parameters": [ { "name": "country_code", "in": "path", "schema": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB')." }, "required": true, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB').", "examples": { "default": { "value": "US" } } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "object", "properties": { "length": { "type": [ "integer", "null" ], "description": "Number of cities in `cities` on success; `-1` when the country has no rows." }, "cities": { "anyOf": [ { "type": "array", "items": { "type": [ "string", "null" ] } }, { "type": "string" } ], "nullable": true, "description": "Array of Shazam city names for the country, or the legacy fallback string `\"Invalid Country or No Cities Found\"` when no rows match." } } } }, "additionalProperties": false }, "examples": { "default": { "value": { "obj": { "length": 3, "cities": [ "Atlanta", "Austin", "Baltimore" ] } } } } } } } } } }, "/api/charts/soundcloud": { "get": { "summary": "SoundCloud Charts (Legacy)", "tags": [ "Charts" ], "operationId": "getSoundcloudCharts", "description": "Legacy SoundCloud charts (deprecated by SoundCloud but retained). Handler runs `QUERY_GET_SOUNDCLOUD_CHARTS` (or `..._RAW` when `raw=true`), merges track metadata, and attaches historical `rankStats`. A nested `soundcloud_user` object is passed through unmodified.", "parameters": [ { "name": "country_code", "in": "query", "schema": { "type": "string", "minLength": 2, "maxLength": 6, "enum": [ "IE", "AU", "NL", "CA", "GLOBAL", "US", "FR", "NZ", "GB", "DE" ], "description": "Country code accepted by the legacy SoundCloud chart pipeline; only the values supported by SoundCloud are valid." }, "required": true, "description": "Country code accepted by the legacy SoundCloud chart pipeline; only the values supported by SoundCloud are valid.", "examples": { "default": { "value": "IE" } } }, { "name": "kind", "in": "query", "schema": { "type": "string", "enum": [ "top", "trending" ], "description": "SoundCloud chart kind (e.g. `trending`, `top`)." }, "required": true, "description": "SoundCloud chart kind (e.g. `trending`, `top`).", "examples": { "default": { "value": "top" } } }, { "name": "genre", "in": "query", "schema": { "type": "string", "enum": [ "soundtrack", "world", "latin", "triphop", "danceedm", "ambient", "jazzblues", "trance", "reggaeton", "metal", "all-music", "classical", "drumbass", "hiphoprap", "dubstep", "alternativerock", "pop", "rock", "folksingersongwriter", "reggae", "disco", "techno", "deephouse", "indie", "rbsoul", "house", "dancehall", "trap", "electronic", "country", "piano" ], "description": "SoundCloud genre filter; values are lowercased. See `CONSTANTS.SOUNDCLOUD_CHART_GENRES` for the supported list." }, "required": true, "description": "SoundCloud genre filter; values are lowercased. See `CONSTANTS.SOUNDCLOUD_CHART_GENRES` for the supported list.", "examples": { "default": { "value": "soundtrack" } } }, { "name": "date", "in": "query", "schema": { "anyOf": [ { "type": "string", "format": "date-time", "x-required": true } ], "description": "Date for the time-slice (YYYY-MM-DD). Required unless `latest=true`." }, "required": false, "description": "Date for the time-slice (YYYY-MM-DD). Required unless `latest=true`." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, "required": false, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, { "name": "raw", "in": "query", "schema": { "type": "boolean", "description": "If true (default), exclude `peak_rank`/`peak_date` for faster response. Set to false to include peak fields.", "default": true }, "required": false, "description": "If true (default), exclude `peak_rank`/`peak_date` for faster response. Set to false to include peak fields." }, { "name": "chart_type", "in": "query", "schema": { "type": "string", "enum": [ "trending", "track" ], "description": "Source SoundCloud chart table: `trending` or `track`. Defaults to `track`.", "default": "track" }, "required": false, "description": "Source SoundCloud chart table: `trending` or `track`. Defaults to `track`." }, { "name": "latest", "in": "query", "schema": { "type": "boolean", "description": "If true, use the most recently available date and ignore `date`." }, "required": false, "description": "If true, use the most recently available date and ignore `date`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "object", "properties": { "length": { "type": [ "integer", "null" ], "description": "Number of chart rows in `data`." }, "data": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 2147483647 }, { "type": "string" } ], "nullable": true, "description": "Platform-side track ID (or Chartmetric ID for ISRC-keyed lookups)." }, "name": { "type": [ "string", "null" ], "description": "Track name." }, "isrc": { "type": [ "string", "null" ], "description": "International Standard Recording Code." }, "image_url": { "type": [ "string", "null" ], "description": "Track or album cover image URL." }, "description": { "type": [ "string", "null" ], "description": "Track description (free-text metadata)." }, "tags": { "type": [ "string", "null" ], "description": "Comma-separated genre tags for the track." }, "cm_track": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Chartmetric track ID." }, "cm_artist": { "type": [ "array", "null" ], "items": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647 }, "description": "Chartmetric artist IDs of the track artists." }, "artist_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Track artist names." }, "code2s": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Country codes per artist (ISO 3166-1 alpha-2)." }, "artist_images": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Artist profile image URLs." }, "artist_covers": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Artist cover image URLs." }, "spotify_track_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Spotify track IDs." }, "spotify_album_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Spotify album IDs." }, "spotify_duration_ms": { "type": [ "integer", "null" ], "description": "Track duration on Spotify in milliseconds." }, "itunes_track_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "iTunes track IDs." }, "itunes_album_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "iTunes album IDs." }, "itunes_artist_ids": { "type": [ "array", "null" ], "items": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "nullable": true }, "description": "iTunes artist IDs." }, "itunes_artist_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "iTunes artist names." }, "storefronts": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "iTunes/Apple Music storefront codes (ISO 3166-1 alpha-2 lowercased)." }, "deezer_track_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Deezer track IDs." }, "deezer_album_ids": { "type": [ "array", "null" ], "items": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true }, "description": "Deezer album IDs." }, "deezer_duration": { "type": [ "integer", "null" ], "description": "Track duration on Deezer in seconds." }, "amazon_track_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Amazon track IDs." }, "amazon_album_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Amazon album IDs." }, "album_ids": { "type": [ "array", "null" ], "items": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 2147483647 }, { "type": "string" } ], "nullable": true }, "description": "Chartmetric album IDs." }, "album_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Album names." }, "album_upc": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Album UPC values." }, "album_label": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Record labels for the album(s)." }, "release_dates": { "type": [ "array", "null" ], "items": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string" } ], "nullable": true }, "description": "Album release dates." }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string" } ], "nullable": true, "description": "Track-record creation timestamp." }, "modified_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string" } ], "nullable": true, "description": "Track-record last-modified timestamp." }, "rank": { "type": [ "integer", "null" ], "description": "Current chart rank (1 = top)." }, "pre_rank": { "type": [ "integer", "null" ], "description": "Position on the previous chart period." }, "peak_rank": { "type": [ "integer", "null" ], "description": "Best (lowest-numbered) rank reached." }, "peak_date": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string" } ], "nullable": true, "description": "Date `peak_rank` was achieved. Omitted when `raw=true`." }, "added_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string" } ], "nullable": true, "description": "Timestamp the row was added to the chart." }, "velocity": { "type": [ "number", "null" ], "format": "float", "description": "Rank-velocity signal (positive = climbing)." }, "time_on_chart": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Length of time on the chart." }, "country": { "type": [ "string", "null" ], "description": "Chart country name." }, "genre": { "type": [ "string", "null" ], "description": "Chart genre." }, "kind": { "type": [ "string", "null" ], "description": "SoundCloud chart kind (e.g. `trending`, `top`)." }, "soundcloud_track_id": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "SoundCloud track ID." }, "playcount_all": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "All-time SoundCloud play count." }, "playcount_weekly": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Weekly SoundCloud play count." }, "artwork_url": { "type": [ "string", "null" ], "description": "SoundCloud track artwork URL." }, "permalink_url": { "type": [ "string", "null" ], "description": "SoundCloud track permalink URL." }, "public": { "type": [ "boolean", "null" ], "description": "Whether the SoundCloud track is publicly visible." }, "publisher": { "type": [ "string", "null" ], "description": "Track publisher name." }, "writer_composer": { "type": [ "string", "null" ], "description": "Track writer/composer name." }, "artist": { "type": [ "string", "null" ], "description": "SoundCloud-side artist name string." }, "album_title": { "type": [ "string", "null" ], "description": "SoundCloud-side album title." }, "soundcloud_user": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "integer", "null" ], "description": "SoundCloud user ID." }, "kind": { "type": [ "string", "null" ], "description": "Account type (`user`, `group`, ...)." }, "username": { "type": [ "string", "null" ], "description": "SoundCloud username." }, "permalink": { "type": [ "string", "null" ], "description": "SoundCloud profile permalink slug." }, "permalink_url": { "type": [ "string", "null" ], "description": "Full SoundCloud profile URL." }, "uri": { "type": [ "string", "null" ], "description": "SoundCloud API resource URI." }, "urn": { "type": [ "string", "null" ], "description": "SoundCloud URN identifier." }, "first_name": { "type": [ "string", "null" ], "description": "Account first name." }, "last_name": { "type": [ "string", "null" ], "description": "Account last name." }, "full_name": { "type": [ "string", "null" ], "description": "Account full name." }, "description": { "type": [ "string", "null" ], "description": "Profile bio / description." }, "avatar_url": { "type": [ "string", "null" ], "description": "Profile avatar URL." }, "city": { "type": [ "string", "null" ], "description": "Account city." }, "country_code": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-2 country code." }, "verified": { "type": [ "boolean", "null" ], "description": "Whether the account is verified." }, "visuals": { "type": [ "string", "null" ], "description": "Profile visuals payload." }, "create_at": { "type": [ "string", "null" ], "description": "Account creation timestamp." }, "last_modified": { "type": [ "string", "null" ], "description": "Account last-modified timestamp." }, "followers_count": { "type": [ "integer", "null" ], "description": "Number of followers." }, "followings_count": { "type": [ "integer", "null" ], "description": "Number of accounts followed." }, "comments_count": { "type": [ "integer", "null" ], "description": "Number of comments authored." }, "groups_count": { "type": [ "integer", "null" ], "description": "Number of groups joined." }, "likes_count": { "type": [ "integer", "null" ], "description": "Number of likes given." }, "playlist_likes_count": { "type": [ "integer", "null" ], "description": "Number of playlist likes." }, "playlist_count": { "type": [ "integer", "null" ], "description": "Number of playlists." }, "reposts_count": { "type": [ "integer", "null" ], "description": "Number of reposts." }, "track_count": { "type": [ "integer", "null" ], "description": "Number of uploaded tracks." }, "creator_subscriptions": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "product": { "type": [ "object", "null" ], "properties": {}, "description": "Subscribed product info (opaque)." } } }, "description": "Creator subscription records." }, "badges": { "type": [ "object", "null" ], "properties": { "pro_unlimited": { "type": [ "boolean", "null" ], "description": "True when the account has Pro Unlimited subscription." }, "verified": { "type": [ "boolean", "null" ], "description": "Mirror of the top-level verified flag." } }, "description": "Account-badge flags." } }, "description": "Embedded SoundCloud user object (uploader profile fields)." }, "rankStats": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "rank": { "type": [ "integer", "null" ], "description": "Rank at `timestp` (1 = top)." }, "timestp": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string" } ], "nullable": true, "description": "Timestamp of the rank sample." } } }, "description": "Per-row historical rank samples." } } }, "description": "Chart rows ordered by rank (1 = highest)." } } } }, "additionalProperties": false } } } } } } }, "/api/charts/beatport": { "get": { "summary": "Beatport Charts", "tags": [ "Charts" ], "operationId": "getBeatportCharts", "description": "Beatport track charts (weekly). Handler runs `QUERY_GET_BEATPORT_CHARTS` keyed by ISRC, merges cross-platform track metadata, and attaches historical `rankStats` from `QUERY_GET_TRACK_RANKINGS.BEATPORT`.", "parameters": [ { "name": "genre", "in": "query", "schema": { "type": "string", "description": "Beatport genre filter. Use `/api/charts/genres/beatport` to retrieve the available genre names." }, "required": true, "description": "Beatport genre filter. Use `/api/charts/genres/beatport` to retrieve the available genre names.", "examples": { "default": { "value": "example" } } }, { "name": "date", "in": "query", "schema": { "anyOf": [ { "type": "string", "format": "date-time", "x-required": true } ], "description": "Date for the time-slice (YYYY-MM-DD). Required unless `latest=true`." }, "required": false, "description": "Date for the time-slice (YYYY-MM-DD). Required unless `latest=true`." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, "required": false, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, { "name": "latest", "in": "query", "schema": { "type": "boolean", "description": "If true, use the most recently available date and ignore `date`." }, "required": false, "description": "If true, use the most recently available date and ignore `date`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "object", "properties": { "length": { "type": [ "integer", "null" ], "description": "Number of chart rows in `data`." }, "data": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 2147483647 }, { "type": "string" } ], "nullable": true, "description": "Platform-side track ID (or Chartmetric ID for ISRC-keyed lookups)." }, "name": { "type": [ "string", "null" ], "description": "Track name." }, "isrc": { "type": [ "string", "null" ], "description": "International Standard Recording Code." }, "image_url": { "type": [ "string", "null" ], "description": "Track or album cover image URL." }, "description": { "type": [ "string", "null" ], "description": "Track description (free-text metadata)." }, "tags": { "type": [ "string", "null" ], "description": "Comma-separated genre tags for the track." }, "cm_track": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Chartmetric track ID." }, "cm_artist": { "type": [ "array", "null" ], "items": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647 }, "description": "Chartmetric artist IDs of the track artists." }, "artist_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Track artist names." }, "code2s": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Country codes per artist (ISO 3166-1 alpha-2)." }, "artist_images": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Artist profile image URLs." }, "artist_covers": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Artist cover image URLs." }, "spotify_track_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Spotify track IDs." }, "spotify_album_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Spotify album IDs." }, "spotify_duration_ms": { "type": [ "integer", "null" ], "description": "Track duration on Spotify in milliseconds." }, "itunes_track_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "iTunes track IDs." }, "itunes_album_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "iTunes album IDs." }, "itunes_artist_ids": { "type": [ "array", "null" ], "items": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "nullable": true }, "description": "iTunes artist IDs." }, "itunes_artist_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "iTunes artist names." }, "storefronts": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "iTunes/Apple Music storefront codes (ISO 3166-1 alpha-2 lowercased)." }, "deezer_track_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Deezer track IDs." }, "deezer_album_ids": { "type": [ "array", "null" ], "items": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true }, "description": "Deezer album IDs." }, "deezer_duration": { "type": [ "integer", "null" ], "description": "Track duration on Deezer in seconds." }, "amazon_track_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Amazon track IDs." }, "amazon_album_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Amazon album IDs." }, "album_ids": { "type": [ "array", "null" ], "items": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 2147483647 }, { "type": "string" } ], "nullable": true }, "description": "Chartmetric album IDs." }, "album_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Album names." }, "album_upc": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Album UPC values." }, "album_label": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Record labels for the album(s)." }, "release_dates": { "type": [ "array", "null" ], "items": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string" } ], "nullable": true }, "description": "Album release dates." }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string" } ], "nullable": true, "description": "Track-record creation timestamp." }, "modified_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string" } ], "nullable": true, "description": "Track-record last-modified timestamp." }, "rank": { "type": [ "integer", "null" ], "description": "Current chart rank (1 = top)." }, "pre_rank": { "type": [ "integer", "null" ], "description": "Position on the previous chart period." }, "peak_rank": { "type": [ "integer", "null" ], "description": "Best (lowest-numbered) rank reached." }, "peak_date": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string" } ], "nullable": true, "description": "Date `peak_rank` was achieved." }, "added_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string" } ], "nullable": true, "description": "Timestamp the row was added to the chart." }, "velocity": { "type": [ "number", "null" ], "format": "float", "description": "Rank-velocity signal (positive = climbing)." }, "time_on_chart": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Length of time on the chart." }, "genre": { "type": [ "string", "null" ], "description": "Chart genre on Beatport." }, "beatport": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Beatport track ID." }, "remixers": { "type": [ "string", "null" ], "description": "Track remixer names." }, "bc_label": { "type": [ "string", "null" ], "description": "Beatport label name." }, "track_name": { "type": [ "string", "null" ], "description": "Beatport-side track name (may differ from the canonical `name`)." }, "artist_name": { "type": [ "string", "null" ], "description": "Beatport-side artist name (may differ from the canonical `artist_names`)." }, "rankStats": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "rank": { "type": [ "integer", "null" ], "description": "Rank at `timestp` (1 = top)." }, "timestp": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string" } ], "nullable": true, "description": "Timestamp of the rank sample." } } }, "description": "Per-row historical rank samples." } } }, "description": "Chart rows ordered by rank (1 = highest)." } } } }, "additionalProperties": false } } } } } } }, "/api/charts/tiktok/tracks": { "get": { "summary": "Get TikTok Top-Track Chart", "tags": [ "Charts" ], "operationId": "getTiktokTrackCharts", "description": "Return the TikTok top-track chart — either the post-based chart (default) or the country-based chart when `countryChart=true`. Each row merges track-basic-info with the chart row and a `rankStats` history carrying rank + posts.", "parameters": [ { "name": "date", "in": "query", "schema": { "anyOf": [ { "type": "string", "format": "date-time", "x-required": true } ], "description": "Date for the time-slice (YYYY-MM-DD). Required unless `latest=true`." }, "required": false, "description": "Date for the time-slice (YYYY-MM-DD). Required unless `latest=true`." }, { "name": "interval", "in": "query", "schema": { "type": "string", "enum": [ "daily", "weekly", "monthly", "semi-yearly", "yearly", "all_time" ], "description": "Chart interval (e.g. `daily`, `weekly`, `all_time`); defaults to `all_time`.", "default": "all_time" }, "required": false, "description": "Chart interval (e.g. `daily`, `weekly`, `all_time`); defaults to `all_time`." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum number of items to return per request.", "default": 100 }, "required": false, "description": "Maximum number of items to return per request." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 9900, "description": "Number of items to skip; capped at 9900 because the underlying Elasticsearch window allows at most 10000 results (offset + limit)." }, "required": false, "description": "Number of items to skip; capped at 9900 because the underlying Elasticsearch window allows at most 10000 results (offset + limit)." }, { "name": "countryChart", "in": "query", "schema": { "type": "boolean", "description": "If true, return the country chart and use `code2`. Otherwise, return the post chart.", "default": false }, "required": false, "description": "If true, return the country chart and use `code2`. Otherwise, return the post chart." }, { "name": "code2", "in": "query", "schema": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB').", "default": "US" }, "required": false, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB')." }, { "name": "latest", "in": "query", "schema": { "type": "boolean", "description": "If true, use the most recently available date and ignore `date`." }, "required": false, "description": "If true, use the most recently available date and ignore `date`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "object", "properties": { "length": { "type": "integer", "minimum": 0, "description": "Number of chart rows in `data`." }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ], "description": "Internal chart row ID." }, "tiktok_track_id": { "type": [ "string", "null" ], "description": "TikTok track ID." }, "tiktok": { "type": [ "integer", "null" ], "description": "Internal TikTok chart row ID." }, "tiktok_song_id": { "type": [ "string", "null" ], "description": "TikTok song ID linked to the track." }, "tiktok_artist_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "TikTok artist names." }, "tiktok_track_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "TikTok track IDs." }, "rank": { "type": [ "integer", "null" ], "description": "Current chart rank (1 = top)." }, "posts": { "type": [ "integer", "null" ], "minimum": 0, "description": "Number of TikTok posts using this track over the chosen `interval`." }, "weekly_posts": { "type": [ "integer", "null" ], "minimum": 0, "description": "Posts in the last 7 days." }, "daily_posts": { "type": [ "integer", "null" ], "minimum": 0, "description": "Posts in the last 24 hours." }, "views": { "type": [ "integer", "null" ], "minimum": 0, "description": "Aggregate view count." }, "views_prev": { "type": [ "integer", "null" ], "minimum": 0, "description": "Aggregate view count for the previous period." }, "added_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp the track was added to the chart." }, "velocity": { "type": [ "number", "null" ], "format": "float", "description": "Rank-velocity signal (positive = climbing)." }, "pre_rank": { "type": [ "integer", "null" ], "description": "Position on the previous chart period." }, "peak_rank": { "type": [ "integer", "null" ], "description": "Best (lowest-numbered) rank reached." }, "peak_date": { "type": [ "string", "null" ], "format": "date-time", "description": "Date `peak_rank` was achieved." }, "time_on_chart": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "nullable": true, "description": "Length of time on the chart (integer count of periods or duration string)." }, "rankStats": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "rank": { "type": [ "integer", "null" ], "description": "Rank at `timestp` (1 = top)." }, "posts": { "type": [ "integer", "null" ], "minimum": 0, "description": "Post count at `timestp` (TikTok)." }, "views": { "type": [ "integer", "null" ], "minimum": 0, "description": "View count at `timestp` (YouTube/TikTok video)." }, "timestp": { "anyOf": [ { "type": [ "string", "null" ], "format": "date-time" } ], "description": "Timestamp at which the rank was recorded." } } }, "description": "Historical rank samples with `posts` counts at each timestamp." }, "cm_track": { "type": [ "integer", "null" ], "description": "Chartmetric track ID." }, "name": { "type": [ "string", "null" ], "description": "Track name." }, "isrc": { "type": [ "string", "null" ], "description": "International Standard Recording Code." }, "image_url": { "type": [ "string", "null" ], "description": "Track or album cover image URL." }, "cm_artist": { "anyOf": [ { "type": "integer" }, { "type": "array", "items": { "type": [ "integer", "null" ] } } ], "nullable": true, "description": "Chartmetric artist ID(s) — single value or array depending on platform." }, "artist_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Track artist names." }, "code2s": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Country codes per artist (ISO 3166-1 alpha-2)." }, "artist_images": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Artist profile image URLs." }, "artist_covers": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Artist cover image URLs." }, "album_ids": { "type": [ "array", "null" ], "items": { "type": [ "integer", "null" ] }, "description": "Chartmetric album IDs." }, "album_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Album names." }, "album_upc": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Album UPC values." }, "album_label": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Record labels for the album(s)." }, "release_dates": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Album release dates." }, "artists": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ], "description": "Chartmetric artist ID." }, "name": { "type": [ "string", "null" ], "description": "Artist name." }, "code2": { "type": [ "string", "null" ], "description": "Artist country code (ISO 3166-1 alpha-2)." }, "image_url": { "type": [ "string", "null" ], "description": "Artist image URL." }, "career_stage": { "type": [ "string", "null" ], "description": "Artist career stage (e.g. `undiscovered`, `developing`, `mid-level`, `mainstream`, `superstar`, `legendary`)." } } }, "description": "Normalized artist info objects for the track." }, "album": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": {} } }, { "type": "object", "properties": {} } ], "nullable": true, "description": "Album info object (or array of objects) associated with the track." }, "duration_ms": { "type": [ "integer", "null" ], "description": "Track duration in milliseconds." }, "explicit": { "type": [ "boolean", "null" ], "description": "Whether the track is flagged as explicit." }, "preview_url": { "type": [ "string", "null" ], "description": "Audio preview URL." }, "track_genre": { "anyOf": [ { "type": "string" }, { "type": "array", "items": {} } ], "nullable": true, "description": "Track genre(s) — string or array of strings." }, "spotify_popularity": { "type": [ "integer", "null" ], "description": "Spotify popularity score (0–100)." } } }, "description": "Chart rows ordered by rank (1 = highest)." } }, "required": [ "length", "data" ] } }, "required": [ "obj" ] }, "examples": { "default": { "value": { "obj": { "length": 1, "data": [ { "id": 31475, "tiktok_track_id": "Laxed-Siren-Beat-6804093117843770118", "tiktok": 31475, "name": "Laxed - Siren Beat", "isrc": "NZAM02001128", "image_url": "https://p16-sg.tiktokcdn.com/aweme/100x100/tos-alisg-i-0000/79fc18806b60494cb9117888b5a5f621.jpeg", "cm_track": 29203381, "tiktok_artist_names": [ "Jawsh 685" ], "tiktok_track_ids": [ "Laxed-Siren-Beat-6804093117843770118" ], "album_ids": [ 5963064 ], "album_names": [ "Laxed (Siren Beat)" ], "album_upc": [ "9420058747152" ], "album_label": [ "Jawsh 685" ], "release_dates": [ "2020-04-24T07:00:00.000Z" ], "rank": 1, "posts": 55300000, "added_at": "2020-10-11T07:00:00.000Z", "velocity": 0, "pre_rank": 1, "peak_rank": 1, "peak_date": "2020-08-27T07:00:00.000Z", "time_on_chart": "171", "rankStats": [ { "rank": 1, "posts": 55300000, "timestp": "2020-10-04T07:00:00.000Z" } ], "views": 411800, "views_prev": 380000 } ] } } } } } } } } } }, "/api/charts/tiktok/videos": { "get": { "summary": "Get TikTok Top-Video Chart", "tags": [ "Charts" ], "operationId": "getTiktokVideoCharts", "description": "Return the TikTok top-video chart. Each row merges video-track-basic-info with the chart row and carries both `rankStats` (rank + views history) and `viewStats` (views-only slice of the same history).", "parameters": [ { "name": "date", "in": "query", "schema": { "anyOf": [ { "type": "string", "format": "date-time", "x-required": true } ], "description": "Date for the time-slice (YYYY-MM-DD). Required unless `latest=true`." }, "required": false, "description": "Date for the time-slice (YYYY-MM-DD). Required unless `latest=true`." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "maximum": 100, "description": "Maximum entries returned (≤100)." }, "required": false, "description": "Maximum entries returned (≤100)." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 9900, "description": "Number of items to skip; capped at 9900 because the underlying Elasticsearch window allows at most 10000 results (offset + limit)." }, "required": false, "description": "Number of items to skip; capped at 9900 because the underlying Elasticsearch window allows at most 10000 results (offset + limit)." }, { "name": "latest", "in": "query", "schema": { "type": "boolean", "description": "If true, use the most recently available date and ignore `date`." }, "required": false, "description": "If true, use the most recently available date and ignore `date`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "object", "properties": { "length": { "type": "integer", "minimum": 0, "description": "Number of chart rows in `data`." }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "nullable": true, "description": "TikTok video ID (Snowflake IDs may exceed int32 → string)." }, "tiktok_video": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "nullable": true, "description": "TikTok video ID. Same value as `tiktok_video_id`." }, "rank": { "type": [ "integer", "null" ], "description": "Current chart rank (1 = top)." }, "added_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp the video was added to the chart." }, "velocity": { "type": [ "number", "null" ], "format": "float", "description": "Rank-velocity signal (positive = climbing)." }, "pre_rank": { "type": [ "integer", "null" ], "description": "Position on the previous chart period." }, "peak_rank": { "type": [ "integer", "null" ], "description": "Best (lowest-numbered) rank reached." }, "peak_date": { "type": [ "string", "null" ], "format": "date-time", "description": "Date `peak_rank` was achieved." }, "time_on_chart": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "nullable": true, "description": "Length of time on the chart (integer count of periods or duration string)." }, "views": { "type": [ "integer", "null" ], "minimum": 0, "description": "Total view count for the video." }, "likes": { "type": [ "integer", "null" ], "minimum": 0, "description": "Total like count for the video." }, "comments": { "type": [ "integer", "null" ], "minimum": 0, "description": "Total comment count for the video." }, "rankStats": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "rank": { "type": [ "integer", "null" ], "description": "Rank at `timestp` (1 = top)." }, "posts": { "type": [ "integer", "null" ], "minimum": 0, "description": "Post count at `timestp` (TikTok)." }, "views": { "type": [ "integer", "null" ], "minimum": 0, "description": "View count at `timestp` (YouTube/TikTok video)." }, "timestp": { "anyOf": [ { "type": [ "string", "null" ], "format": "date-time" } ], "description": "Timestamp at which the rank was recorded." } } }, "description": "Historical rank samples with `views` counts at each timestamp." }, "viewStats": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "views": { "type": [ "integer", "null" ], "minimum": 0, "description": "View count at `timestp`." }, "timestp": { "anyOf": [ { "type": [ "string", "null" ], "format": "date-time" } ], "description": "Timestamp of the view-count sample." } } }, "description": "Historical view-count samples (views-only slice of `rankStats`)." }, "cm_track": { "type": [ "integer", "null" ], "description": "Chartmetric track ID." }, "name": { "type": [ "string", "null" ], "description": "Track name." }, "isrc": { "type": [ "string", "null" ], "description": "International Standard Recording Code." }, "image_url": { "type": [ "string", "null" ], "description": "Track or album cover image URL." }, "cm_artist": { "anyOf": [ { "type": "integer" }, { "type": "array", "items": { "type": [ "integer", "null" ] } } ], "nullable": true, "description": "Chartmetric artist ID(s) — single value or array depending on platform." }, "artist_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Track artist names." }, "code2s": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Country codes per artist (ISO 3166-1 alpha-2)." }, "artist_images": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Artist profile image URLs." }, "artist_covers": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Artist cover image URLs." }, "album_ids": { "type": [ "array", "null" ], "items": { "type": [ "integer", "null" ] }, "description": "Chartmetric album IDs." }, "album_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Album names." }, "album_upc": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Album UPC values." }, "album_label": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Record labels for the album(s)." }, "release_dates": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Album release dates." }, "artists": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ], "description": "Chartmetric artist ID." }, "name": { "type": [ "string", "null" ], "description": "Artist name." }, "code2": { "type": [ "string", "null" ], "description": "Artist country code (ISO 3166-1 alpha-2)." }, "image_url": { "type": [ "string", "null" ], "description": "Artist image URL." }, "career_stage": { "type": [ "string", "null" ], "description": "Artist career stage (e.g. `undiscovered`, `developing`, `mid-level`, `mainstream`, `superstar`, `legendary`)." } } }, "description": "Normalized artist info objects for the track." }, "album": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": {} } }, { "type": "object", "properties": {} } ], "nullable": true, "description": "Album info object (or array of objects) associated with the track." }, "duration_ms": { "type": [ "integer", "null" ], "description": "Track duration in milliseconds." }, "explicit": { "type": [ "boolean", "null" ], "description": "Whether the track is flagged as explicit." }, "preview_url": { "type": [ "string", "null" ], "description": "Audio preview URL." }, "track_genre": { "anyOf": [ { "type": "string" }, { "type": "array", "items": {} } ], "nullable": true, "description": "Track genre(s) — string or array of strings." }, "spotify_popularity": { "type": [ "integer", "null" ], "description": "Spotify popularity score (0–100)." } } }, "description": "Chart rows ordered by rank (1 = highest)." } }, "required": [ "length", "data" ] } }, "required": [ "obj" ] }, "examples": { "default": { "value": { "obj": { "length": 1, "data": [ { "id": "6981234567890123456", "tiktok_video": "6981234567890123456", "name": "Viral clip", "rank": 1, "added_at": "2024-05-01T00:00:00.000Z", "velocity": 0, "pre_rank": 1, "peak_rank": 1, "peak_date": "2024-04-28T00:00:00.000Z", "time_on_chart": "12", "views": 411800, "likes": 72500, "comments": 222, "rankStats": [ { "rank": 1, "views": 411800, "timestp": "2024-04-30T00:00:00.000Z" } ], "viewStats": [ { "views": 411800, "timestp": "2024-04-30T00:00:00.000Z" } ] } ] } } } } } } } } } }, "/api/charts/tiktok/users": { "get": { "summary": "Get TikTok Top-User Chart", "tags": [ "Charts" ], "operationId": "getTiktokUserCharts", "description": "Return the TikTok top-user chart by `type` (`likes` / `followers`) and `interval` (`daily` / `weekly` / `all_time`). Each row merges the TikTok user basic info (from `#getArtistInfoForPlatformMap`) with the chart row + `rankStats` history.", "parameters": [ { "name": "date", "in": "query", "schema": { "anyOf": [ { "type": "string", "format": "date-time", "x-required": true } ], "description": "Date for the time-slice (YYYY-MM-DD). Required unless `latest=true`." }, "required": false, "description": "Date for the time-slice (YYYY-MM-DD). Required unless `latest=true`." }, { "name": "interval", "in": "query", "schema": { "type": "string", "enum": [ "daily", "weekly", "monthly", "semi-yearly", "yearly", "all_time" ], "description": "Chart interval (e.g. `daily`, `weekly`, `monthly`)." }, "required": false, "description": "Chart interval (e.g. `daily`, `weekly`, `monthly`)." }, { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "likes", "followers" ], "description": "TikTok user chart type (e.g. `likes`, `followers`, `viewer_hours`)." }, "required": true, "description": "TikTok user chart type (e.g. `likes`, `followers`, `viewer_hours`).", "examples": { "default": { "value": "likes" } } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "maximum": 100, "description": "Maximum entries returned (≤100)." }, "required": false, "description": "Maximum entries returned (≤100)." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 9900, "description": "Number of items to skip; capped at 9900 because the underlying Elasticsearch window allows at most 10000 results (offset + limit)." }, "required": false, "description": "Number of items to skip; capped at 9900 because the underlying Elasticsearch window allows at most 10000 results (offset + limit)." }, { "name": "latest", "in": "query", "schema": { "type": "boolean", "description": "If true, use the most recently available date and ignore `date`." }, "required": false, "description": "If true, use the most recently available date and ignore `date`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "object", "properties": { "length": { "type": "integer", "minimum": 0, "description": "Number of chart rows in `data`." }, "data": { "type": "array", "items": { "type": "object", "properties": { "tiktok_user": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "nullable": true, "description": "TikTok user handle/ID." }, "cm_artist": { "type": [ "integer", "null" ], "description": "Chartmetric artist ID linked to the TikTok user." }, "name": { "type": [ "string", "null" ], "description": "TikTok user name." }, "image_url": { "type": [ "string", "null" ], "description": "User avatar URL." }, "rank": { "type": [ "integer", "null" ], "description": "Current chart rank (1 = top)." }, "added_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp the user was added to the chart." }, "velocity": { "type": [ "number", "null" ], "format": "float", "description": "Rank-velocity signal (positive = climbing)." }, "pre_rank": { "type": [ "integer", "null" ], "description": "Position on the previous chart period." }, "peak_rank": { "type": [ "integer", "null" ], "description": "Best (lowest-numbered) rank reached." }, "peak_date": { "type": [ "string", "null" ], "format": "date-time", "description": "Date `peak_rank` was achieved." }, "time_on_chart": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "nullable": true, "description": "Length of time on the chart (integer count of periods or duration string)." }, "followers": { "type": [ "integer", "null" ], "minimum": 0, "description": "Total followers count." }, "likes": { "type": [ "integer", "null" ], "minimum": 0, "description": "Total likes received across the user's videos." }, "views": { "type": [ "integer", "null" ], "minimum": 0, "description": "Total views across the user's videos." }, "weekly_followers": { "type": [ "integer", "null" ], "minimum": 0, "description": "Followers gained in the last 7 days." }, "daily_followers": { "type": [ "integer", "null" ], "minimum": 0, "description": "Followers gained in the last 24 hours." }, "weekly_likes": { "type": [ "integer", "null" ], "minimum": 0, "description": "Likes gained in the last 7 days." }, "daily_likes": { "type": [ "integer", "null" ], "minimum": 0, "description": "Likes gained in the last 24 hours." }, "rankStats": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "rank": { "type": [ "integer", "null" ], "description": "Rank at `timestp` (1 = top)." }, "posts": { "type": [ "integer", "null" ], "minimum": 0, "description": "Post count at `timestp` (TikTok)." }, "views": { "type": [ "integer", "null" ], "minimum": 0, "description": "View count at `timestp` (YouTube/TikTok video)." }, "timestp": { "anyOf": [ { "type": [ "string", "null" ], "format": "date-time" } ], "description": "Timestamp at which the rank was recorded." } } }, "description": "Historical rank samples; entries also carry `followers` for follower-type charts." } } }, "description": "Chart rows ordered by rank (1 = highest)." } }, "required": [ "length", "data" ] } }, "required": [ "obj" ] }, "examples": { "default": { "value": { "obj": { "length": 1, "data": [ { "tiktok_user": "sample_user", "cm_artist": 123456, "name": "Sample User", "image_url": "https://example.com/avatar.jpg", "rank": 1, "added_at": "2024-05-01T00:00:00.000Z", "velocity": 0, "pre_rank": 1, "peak_rank": 1, "peak_date": "2024-04-28T00:00:00.000Z", "time_on_chart": "12", "followers": 15000000, "rankStats": [ { "rank": 1, "followers": 15000000, "timestp": "2024-04-30T00:00:00.000Z" } ] } ] } } } } } } } } } }, "/api/charts/tiktok/sounds": { "get": { "summary": "Get TikTok Sound Chart", "tags": [ "Charts" ], "operationId": "getTiktokSoundCharts", "description": "Return the TikTok sound chart for one country, ranked by videos created in the last 24 hours. Pass `country` for a country chart or `WW` (the default) for the worldwide chart. Rows carry the sound's own metrics plus the linked song's metadata, and `cm_track` when the sound could be matched to a Chartmetric track.", "parameters": [ { "name": "date", "in": "query", "schema": { "anyOf": [ { "type": "string", "format": "date-time", "x-required": true } ], "description": "Date for the time-slice (YYYY-MM-DD). Required unless `latest=true`." }, "required": false, "description": "Date for the time-slice (YYYY-MM-DD). Required unless `latest=true`." }, { "name": "country", "in": "query", "schema": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code (e.g. 'US', 'BR'), or 'WW' for the worldwide chart. Defaults to 'WW'.", "default": "WW" }, "required": false, "description": "ISO 3166-1 alpha-2 country code (e.g. 'US', 'BR'), or 'WW' for the worldwide chart. Defaults to 'WW'." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum entries returned (≤100).", "default": 100 }, "required": false, "description": "Maximum entries returned (≤100)." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Number of rows to skip, for paging through the chart (≤10000)." }, "required": false, "description": "Number of rows to skip, for paging through the chart (≤10000)." }, { "name": "latest", "in": "query", "schema": { "type": "boolean", "description": "If true, use the most recently available date and ignore `date`." }, "required": false, "description": "If true, use the most recently available date and ignore `date`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "object", "properties": { "length": { "type": "integer", "minimum": 0, "description": "Number of chart rows in `data`." }, "data": { "type": "array", "items": { "type": "object", "properties": { "timestp": { "type": "string", "description": "Charting date (`YYYY-MM-DD`) the row was captured for." }, "country": { "type": "string", "description": "Country whose chart this row belongs to; `WW` for worldwide." }, "rank": { "type": [ "integer", "null" ], "description": "Chart rank (1 = top)." }, "tiktok_sound_id": { "type": "string", "description": "TikTok sound ID." }, "tiktok_name_of_sound": { "type": [ "string", "null" ], "description": "Sound name as shown on TikTok." }, "tiktok_sound_creator_name": { "type": [ "string", "null" ], "description": "Display name of the account that created the sound." }, "tiktok_image_url": { "type": [ "string", "null" ], "description": "Sound artwork URL." }, "tiktok_play_url": { "type": [ "string", "null" ], "description": "Direct audio URL for the sound." }, "tiktok_official_link": { "type": [ "string", "null" ], "description": "TikTok page for the sound." }, "tiktok_last_24_hours_video_count": { "type": [ "integer", "null" ], "minimum": 0, "description": "Videos created with this sound in the last 24 hours. Drives the ranking." }, "tiktok_last_24_hours_video_percentage": { "type": [ "number", "null" ], "format": "float", "description": "Change in 24-hour video count versus the previous day, as a percentage." }, "tiktok_last_7_days_video_count": { "type": [ "integer", "null" ], "minimum": 0, "description": "Videos created with this sound in the last 7 days." }, "total_video_views": { "type": [ "integer", "null" ], "minimum": 0, "description": "Total views across all videos using this sound." }, "song_name": { "type": [ "string", "null" ], "description": "Name of the song the sound is taken from." }, "artists": { "type": [ "string", "null" ], "description": "Artist name(s) for the linked song, as a single display string." }, "song_image_url": { "type": [ "string", "null" ], "description": "Cover art URL for the linked song." }, "spotify_id": { "type": [ "string", "null" ], "description": "Spotify track ID of the linked song." }, "label_name": { "type": [ "string", "null" ], "description": "Label associated with the linked song." }, "sound_create_date": { "type": [ "string", "null" ], "description": "Date (`YYYY-MM-DD`) the sound was created on TikTok, or `null` when unknown." }, "cm_track": { "type": [ "integer", "null" ], "description": "Chartmetric track ID the sound resolves to, or `null` when no match was found." }, "is_ai_generated": { "type": "boolean", "description": "Whether TikTok flags the sound as AI-generated." } }, "required": [ "timestp", "country", "tiktok_sound_id" ] }, "description": "Chart rows ordered by rank (1 = highest)." } }, "required": [ "length", "data" ] } }, "required": [ "obj" ] }, "examples": { "default": { "value": { "obj": { "length": 1, "data": [ { "timestp": "2026-08-11", "country": "WW", "rank": 1, "tiktok_sound_id": "7123456789012345678", "tiktok_name_of_sound": "original sound - sample_creator", "tiktok_sound_creator_name": "Sample Creator", "tiktok_image_url": "https://example.com/sound.jpeg", "tiktok_play_url": "https://example.com/sound.mp3", "tiktok_official_link": "https://www.tiktok.com/music/sample-7123456789012345678", "tiktok_last_24_hours_video_count": 128450, "tiktok_last_24_hours_video_percentage": 12.4, "tiktok_last_7_days_video_count": 794300, "total_video_views": 1843200000, "song_name": "Sample Song", "artists": "Sample Artist", "song_image_url": "https://example.com/cover.jpeg", "spotify_id": "4cOdK2wGLETKBW3PvgPWqT", "label_name": "Sample Records", "sound_create_date": "2026-05-02", "cm_track": 987654, "is_ai_generated": false } ] } } } } } } } } } }, "/api/charts/tiktok/tracks/{chart_type}": { "get": { "summary": "Get TikTok Tracks Chart by Type (V2 via CCC)", "tags": [ "Charts" ], "operationId": "getTiktokTrackChartsByType", "description": "Return the TikTok tracks chart for a given `chart_type` (`popular` / `breakout`). Uses the CCC `cm_chart_cache_v2` pipeline (`Charts.getChartsFromCH` → `#hydrateChartRowsByEntity`) and returns a bare array under `obj` (NOT wrapped in `{ length, data }`).", "parameters": [ { "name": "chart_type", "in": "path", "schema": { "type": "string", "enum": [ "popular", "breakout" ], "description": "TikTok track chart type (`popular` or `breakout`)." }, "required": true, "description": "TikTok track chart type (`popular` or `breakout`).", "examples": { "default": { "value": "popular" } } }, { "name": "date", "in": "query", "schema": { "anyOf": [ { "type": "string", "format": "date-time", "x-required": true } ], "description": "Date for the time-slice (YYYY-MM-DD). Required unless `latest=true`." }, "required": false, "description": "Date for the time-slice (YYYY-MM-DD). Required unless `latest=true`." }, { "name": "interval", "in": "query", "schema": { "type": "string", "enum": [ "weekly" ], "description": "Chart interval; only `weekly` is supported on this endpoint." }, "required": false, "description": "Chart interval; only `weekly` is supported on this endpoint." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum number of items to return per request.", "default": 100 }, "required": false, "description": "Maximum number of items to return per request." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 9900, "description": "Number of items to skip; capped at 9900 because the underlying Elasticsearch window allows at most 10000 results (offset + limit)." }, "required": false, "description": "Number of items to skip; capped at 9900 because the underlying Elasticsearch window allows at most 10000 results (offset + limit)." }, { "name": "code2", "in": "query", "schema": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB').", "default": "US" }, "required": false, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB')." }, { "name": "latest", "in": "query", "schema": { "type": "boolean", "description": "If true, use the most recently available date and ignore `date`." }, "required": false, "description": "If true, use the most recently available date and ignore `date`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "array", "items": { "type": "object", "properties": { "entityId": { "type": [ "integer", "null" ], "description": "Internal Chartmetric entity ID for the chart row." }, "targetId": { "type": [ "string", "null" ], "description": "Platform-side track/video/user ID (string; some platform IDs exceed int32)." }, "duration": { "type": [ "string", "null" ], "description": "Chart duration window (e.g. `daily`, `weekly`, `monthly`)." }, "country": { "type": [ "string", "null" ], "description": "Country code (ISO 3166-1 alpha-2; empty string for global charts)." }, "cityId": { "type": [ "integer", "null" ], "description": "Chartmetric city ID, or 0 when not city-scoped." }, "genre": { "type": [ "string", "null" ], "description": "Chart genre." }, "rank": { "type": [ "integer", "null" ], "description": "Current chart rank (1 = top)." }, "rankDiff": { "type": [ "integer", "null" ], "description": "Rank change from the previous period (negative = climbed)." }, "rankTrend": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": {} } } ], "nullable": true, "description": "Historical rank samples (array of `{ timestp, rank }` entries)." }, "peakDate": { "type": [ "string", "null" ], "format": "date-time", "description": "Date the entity achieved its peak rank." }, "peakRank": { "type": [ "integer", "null" ], "description": "Best (lowest-numbered) rank achieved." }, "velocity7Day": { "type": [ "number", "null" ], "format": "float", "description": "7-day rank velocity (positive = trending up)." }, "periodsOnChart": { "type": [ "integer", "null" ], "description": "Total chart periods (days/weeks/months) on the chart." }, "consecutivePeriods": { "type": [ "integer", "null" ], "description": "Consecutive chart periods without falling off." }, "chartedDate": { "type": [ "string", "null" ], "format": "date-time", "description": "Date of the chart row." }, "name": { "type": [ "string", "null" ], "description": "Track name." }, "imageUrl": { "type": [ "string", "null" ], "description": "Track or album cover image URL." }, "countriesChartingCount": { "type": [ "integer", "null" ], "description": "Number of countries on which the track is currently charting." }, "previewUrl": { "type": [ "string", "null" ], "description": "Audio preview URL." }, "artists": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "careerStage": { "type": [ "string", "null" ], "description": "Artist career stage (e.g. `undiscovered`, `developing`, `mid-level`, `mainstream`, `superstar`, `legendary`)." }, "code2": { "type": [ "string", "null" ], "description": "Artist country code (ISO 3166-1 alpha-2)." }, "id": { "type": [ "integer", "null" ], "description": "Chartmetric artist ID." }, "name": { "type": [ "string", "null" ], "description": "Artist name." }, "imageUrl": { "type": [ "string", "null" ], "description": "Artist image URL." } } }, "description": "Artists associated with the track." }, "album": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "integer", "null" ], "description": "Chartmetric album ID." }, "name": { "type": [ "string", "null" ], "description": "Album name." }, "label": { "type": [ "string", "null" ], "description": "Album record label." }, "releaseDate": { "type": [ "string", "null" ], "format": "date-time", "description": "Album release date." } }, "description": "Album the track belongs to." }, "isrc": { "type": [ "string", "null" ], "description": "International Standard Recording Code." }, "entity": { "type": [ "object", "null" ], "properties": { "genre": { "type": [ "string", "null" ], "description": "Entity-level genre (when distinct from chart genre)." } }, "description": "Additional entity-level metadata." }, "externalId": { "type": [ "string", "null" ], "description": "Platform external ID (e.g. YouTube video ID, TikTok track ID)." }, "externalUrl": { "type": [ "string", "null" ], "description": "Platform external URL." }, "optionalFields": { "type": [ "object", "null" ], "properties": { "artistName": { "type": [ "string", "null" ], "description": "Primary artist name." }, "name": { "type": [ "string", "null" ], "description": "Track name (redundant — mirrors top-level `name`)." }, "imageUrl": { "type": [ "string", "null" ], "description": "Alternate image URL." }, "albumName": { "type": [ "string", "null" ], "description": "Album name." }, "overallRank": { "type": [ "integer", "null" ], "description": "Overall chart rank across all genres / regions." }, "metricValue": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Primary metric value driving the chart sort (varies by platform)." }, "score": { "type": [ "number", "null" ], "format": "float", "description": "Internal Chartmetric score for the row." }, "isComeback": { "type": [ "boolean", "null" ], "description": "True when the row is flagged a comeback." }, "plays": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Play count snapshot." }, "totalFollowers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Total follower count snapshot." } }, "description": "Per-chart optional metrics. Population varies by platform; commonly populated keys include `score`, `metricValue`, `isComeback`, `plays`, `totalFollowers`." }, "targetExtras": { "type": [ "object", "null" ], "properties": { "airplayStreams": { "type": [ "integer", "null" ], "minimum": 0, "description": "Airplay stream count snapshot." }, "amazonEdPlaylistCount": { "type": [ "integer", "null" ], "minimum": 0, "description": "Number of Amazon editorial playlists containing the track." }, "amazonPlaylistCount": { "type": [ "integer", "null" ], "minimum": 0, "description": "Number of Amazon playlists containing the track." }, "anghamiLikes": { "type": [ "integer", "null" ], "minimum": 0, "description": "Anghami like count." }, "anghamiPlays": { "type": [ "integer", "null" ], "minimum": 0, "description": "Anghami play count." }, "deezerEdPlaylistCount": { "type": [ "integer", "null" ], "minimum": 0, "description": "Number of Deezer editorial playlists containing the track." }, "deezerEdPlaylistTotalReach": { "type": [ "integer", "null" ], "minimum": 0, "description": "Total follower reach across Deezer editorial playlists." }, "deezerPlaylistCount": { "type": [ "integer", "null" ], "minimum": 0, "description": "Number of Deezer playlists containing the track." }, "deezerPlaylistTotalReach": { "type": [ "integer", "null" ], "minimum": 0, "description": "Total follower reach across Deezer playlists." }, "itunesEdPlaylistCount": { "type": [ "integer", "null" ], "minimum": 0, "description": "Number of iTunes editorial playlists containing the track." }, "itunesPlaylistCount": { "type": [ "integer", "null" ], "minimum": 0, "description": "Number of iTunes playlists containing the track." }, "pandoraLifetimeStationsAdded": { "type": [ "integer", "null" ], "minimum": 0, "description": "Pandora lifetime station-additions count." }, "pandoraLifetimeStreams": { "type": [ "integer", "null" ], "minimum": 0, "description": "Pandora lifetime stream count." }, "shazamCount": { "type": [ "integer", "null" ], "minimum": 0, "description": "Shazam tag count." }, "spotifyEdPlaylistCount": { "type": [ "integer", "null" ], "minimum": 0, "description": "Number of Spotify editorial playlists containing the track." }, "spotifyEdPlaylistTotalReach": { "type": [ "integer", "null" ], "minimum": 0, "description": "Total follower reach across Spotify editorial playlists." }, "spotifyPlaylistCount": { "type": [ "integer", "null" ], "minimum": 0, "description": "Number of Spotify playlists containing the track." }, "spotifyPlaylistTotalReach": { "type": [ "integer", "null" ], "minimum": 0, "description": "Total follower reach across Spotify playlists." }, "spotifyPlays": { "type": [ "integer", "null" ], "minimum": 0, "description": "Spotify play count snapshot." }, "spotifyPopularity": { "type": [ "integer", "null" ], "description": "Spotify popularity score (0–100)." }, "tiktokTopVideosComments": { "type": [ "integer", "null" ], "minimum": 0, "description": "Comment count across the track's top TikTok videos." }, "tiktokTopVideosLikes": { "type": [ "integer", "null" ], "minimum": 0, "description": "Like count across the track's top TikTok videos." }, "tiktokTopVideosViews": { "type": [ "integer", "null" ], "minimum": 0, "description": "View count across the track's top TikTok videos." }, "youtubeComments": { "type": [ "integer", "null" ], "minimum": 0, "description": "YouTube comment count." }, "youtubeLikes": { "type": [ "integer", "null" ], "minimum": 0, "description": "YouTube like count." }, "youtubeViews": { "type": [ "integer", "null" ], "minimum": 0, "description": "YouTube view count." } }, "description": "Cross-platform metric snapshots hydrated from per-target cache rows." }, "isChartGenre": { "type": [ "boolean", "null" ], "description": "True when the track's genre matches the chart's genre filter." } } } } }, "required": [ "obj" ] }, "examples": { "default": { "value": { "obj": [ { "entityId": 15818551, "targetId": "2212754", "name": "My Boo - Hitman's Club Mix", "rank": 1, "chartedDate": "2025-05-05", "country": "US", "imageUrl": "https://i.scdn.co/image/df8c9d9318a5f598dba02de84323d97656d5adbe", "rankDiff": 1, "artists": [ { "careerStage": "mainstream", "code2": "US", "id": 209688, "name": "Ghost Town DJs", "imageUrl": "https://i.scdn.co/image/ab6761610000e5eb156aef8c73890e10b60e94d4" } ], "album": { "id": 903594, "name": "My Boo (Hitman's Club Mix)", "label": "Columbia", "releaseDate": "1996-03-26T00:00:00.000Z" }, "externalId": "My-Boo-Hitman's-Club-Mix-6716386670813399041", "targetExtras": { "airplayStreams": 35174, "spotifyPlays": 160344152, "shazamCount": 3813848, "tiktokTopVideosViews": 79470645 }, "genre": "r&b/soul", "isChartGenre": false } ] } } } } } } } } }, "/api/charts/youtube/shorts/{chartType}": { "get": { "summary": "Get YouTube Shorts Chart", "tags": [ "Charts" ], "operationId": "getYoutubeShortsCharts", "description": "Return the YouTube Shorts chart for `chartType` (`shorts_daily` / `shorts_weekly`) and `code2`. Uses the CCC `cm_chart_cache_v2` pipeline (`Charts.getChartsFromCH` with `platform: \"youtube\"`, `chartEntity: \"track\"`) and returns a bare array under `obj`.", "parameters": [ { "name": "chartType", "in": "path", "schema": { "type": "string", "enum": [ "shorts_daily", "shorts_weekly" ], "description": "YouTube Shorts chart type (`shorts_daily` or `shorts_weekly`)." }, "required": true, "description": "YouTube Shorts chart type (`shorts_daily` or `shorts_weekly`).", "examples": { "default": { "value": "shorts_daily" } } }, { "name": "code2", "in": "query", "schema": { "anyOf": [ { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB')." }, { "type": "string", "enum": [ "GLOBAL" ] } ], "description": "ISO 3166-1 alpha-2 country code (uppercase, e.g. 'US') or the literal 'GLOBAL' for cross-country charts." }, "required": true, "description": "ISO 3166-1 alpha-2 country code (uppercase, e.g. 'US') or the literal 'GLOBAL' for cross-country charts.", "examples": { "default": { "value": "US" } } }, { "name": "date", "in": "query", "schema": { "anyOf": [ { "type": "string", "format": "date-time", "x-required": true } ], "description": "Date for the time-slice (YYYY-MM-DD). Required unless `latest=true`." }, "required": false, "description": "Date for the time-slice (YYYY-MM-DD). Required unless `latest=true`." }, { "name": "latest", "in": "query", "schema": { "type": "boolean", "description": "If true, use the most recently available date and ignore `date`." }, "required": false, "description": "If true, use the most recently available date and ignore `date`." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "description": "Maximum number of items to return per request.", "default": 100 }, "required": false, "description": "Maximum number of items to return per request." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, "required": false, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "array", "items": { "type": "object", "properties": { "entityId": { "type": [ "integer", "null" ], "description": "Internal Chartmetric entity ID for the chart row." }, "targetId": { "type": [ "string", "null" ], "description": "Platform-side track/video/user ID (string; some platform IDs exceed int32)." }, "duration": { "type": [ "string", "null" ], "description": "Chart duration window (e.g. `daily`, `weekly`, `monthly`)." }, "country": { "type": [ "string", "null" ], "description": "Country code (ISO 3166-1 alpha-2; empty string for global charts)." }, "cityId": { "type": [ "integer", "null" ], "description": "Chartmetric city ID, or 0 when not city-scoped." }, "genre": { "type": [ "string", "null" ], "description": "Chart genre." }, "rank": { "type": [ "integer", "null" ], "description": "Current chart rank (1 = top)." }, "rankDiff": { "type": [ "integer", "null" ], "description": "Rank change from the previous period (negative = climbed)." }, "rankTrend": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": {} } } ], "nullable": true, "description": "Historical rank samples (array of `{ timestp, rank }` entries)." }, "peakDate": { "type": [ "string", "null" ], "format": "date-time", "description": "Date the entity achieved its peak rank." }, "peakRank": { "type": [ "integer", "null" ], "description": "Best (lowest-numbered) rank achieved." }, "velocity7Day": { "type": [ "number", "null" ], "format": "float", "description": "7-day rank velocity (positive = trending up)." }, "periodsOnChart": { "type": [ "integer", "null" ], "description": "Total chart periods (days/weeks/months) on the chart." }, "consecutivePeriods": { "type": [ "integer", "null" ], "description": "Consecutive chart periods without falling off." }, "chartedDate": { "type": [ "string", "null" ], "format": "date-time", "description": "Date of the chart row." }, "name": { "type": [ "string", "null" ], "description": "Track name." }, "imageUrl": { "type": [ "string", "null" ], "description": "Track or album cover image URL." }, "countriesChartingCount": { "type": [ "integer", "null" ], "description": "Number of countries on which the track is currently charting." }, "previewUrl": { "type": [ "string", "null" ], "description": "Audio preview URL." }, "artists": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "careerStage": { "type": [ "string", "null" ], "description": "Artist career stage (e.g. `undiscovered`, `developing`, `mid-level`, `mainstream`, `superstar`, `legendary`)." }, "code2": { "type": [ "string", "null" ], "description": "Artist country code (ISO 3166-1 alpha-2)." }, "id": { "type": [ "integer", "null" ], "description": "Chartmetric artist ID." }, "name": { "type": [ "string", "null" ], "description": "Artist name." }, "imageUrl": { "type": [ "string", "null" ], "description": "Artist image URL." } } }, "description": "Artists associated with the track." }, "album": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "integer", "null" ], "description": "Chartmetric album ID." }, "name": { "type": [ "string", "null" ], "description": "Album name." }, "label": { "type": [ "string", "null" ], "description": "Album record label." }, "releaseDate": { "type": [ "string", "null" ], "format": "date-time", "description": "Album release date." } }, "description": "Album the track belongs to." }, "isrc": { "type": [ "string", "null" ], "description": "International Standard Recording Code." }, "entity": { "type": [ "object", "null" ], "properties": { "genre": { "type": [ "string", "null" ], "description": "Entity-level genre (when distinct from chart genre)." } }, "description": "Additional entity-level metadata." }, "externalId": { "type": [ "string", "null" ], "description": "Platform external ID (e.g. YouTube video ID, TikTok track ID)." }, "externalUrl": { "type": [ "string", "null" ], "description": "Platform external URL." }, "optionalFields": { "type": [ "object", "null" ], "properties": { "artistName": { "type": [ "string", "null" ], "description": "Primary artist name." }, "name": { "type": [ "string", "null" ], "description": "Track name (redundant — mirrors top-level `name`)." }, "imageUrl": { "type": [ "string", "null" ], "description": "Alternate image URL." }, "albumName": { "type": [ "string", "null" ], "description": "Album name." }, "overallRank": { "type": [ "integer", "null" ], "description": "Overall chart rank across all genres / regions." }, "metricValue": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Primary metric value driving the chart sort (varies by platform)." }, "score": { "type": [ "number", "null" ], "format": "float", "description": "Internal Chartmetric score for the row." }, "isComeback": { "type": [ "boolean", "null" ], "description": "True when the row is flagged a comeback." }, "plays": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Play count snapshot." }, "totalFollowers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Total follower count snapshot." } }, "description": "Per-chart optional metrics. Population varies by platform; commonly populated keys include `score`, `metricValue`, `isComeback`, `plays`, `totalFollowers`." }, "targetExtras": { "type": [ "object", "null" ], "properties": { "airplayStreams": { "type": [ "integer", "null" ], "minimum": 0, "description": "Airplay stream count snapshot." }, "amazonEdPlaylistCount": { "type": [ "integer", "null" ], "minimum": 0, "description": "Number of Amazon editorial playlists containing the track." }, "amazonPlaylistCount": { "type": [ "integer", "null" ], "minimum": 0, "description": "Number of Amazon playlists containing the track." }, "anghamiLikes": { "type": [ "integer", "null" ], "minimum": 0, "description": "Anghami like count." }, "anghamiPlays": { "type": [ "integer", "null" ], "minimum": 0, "description": "Anghami play count." }, "deezerEdPlaylistCount": { "type": [ "integer", "null" ], "minimum": 0, "description": "Number of Deezer editorial playlists containing the track." }, "deezerEdPlaylistTotalReach": { "type": [ "integer", "null" ], "minimum": 0, "description": "Total follower reach across Deezer editorial playlists." }, "deezerPlaylistCount": { "type": [ "integer", "null" ], "minimum": 0, "description": "Number of Deezer playlists containing the track." }, "deezerPlaylistTotalReach": { "type": [ "integer", "null" ], "minimum": 0, "description": "Total follower reach across Deezer playlists." }, "itunesEdPlaylistCount": { "type": [ "integer", "null" ], "minimum": 0, "description": "Number of iTunes editorial playlists containing the track." }, "itunesPlaylistCount": { "type": [ "integer", "null" ], "minimum": 0, "description": "Number of iTunes playlists containing the track." }, "pandoraLifetimeStationsAdded": { "type": [ "integer", "null" ], "minimum": 0, "description": "Pandora lifetime station-additions count." }, "pandoraLifetimeStreams": { "type": [ "integer", "null" ], "minimum": 0, "description": "Pandora lifetime stream count." }, "shazamCount": { "type": [ "integer", "null" ], "minimum": 0, "description": "Shazam tag count." }, "spotifyEdPlaylistCount": { "type": [ "integer", "null" ], "minimum": 0, "description": "Number of Spotify editorial playlists containing the track." }, "spotifyEdPlaylistTotalReach": { "type": [ "integer", "null" ], "minimum": 0, "description": "Total follower reach across Spotify editorial playlists." }, "spotifyPlaylistCount": { "type": [ "integer", "null" ], "minimum": 0, "description": "Number of Spotify playlists containing the track." }, "spotifyPlaylistTotalReach": { "type": [ "integer", "null" ], "minimum": 0, "description": "Total follower reach across Spotify playlists." }, "spotifyPlays": { "type": [ "integer", "null" ], "minimum": 0, "description": "Spotify play count snapshot." }, "spotifyPopularity": { "type": [ "integer", "null" ], "description": "Spotify popularity score (0–100)." }, "tiktokTopVideosComments": { "type": [ "integer", "null" ], "minimum": 0, "description": "Comment count across the track's top TikTok videos." }, "tiktokTopVideosLikes": { "type": [ "integer", "null" ], "minimum": 0, "description": "Like count across the track's top TikTok videos." }, "tiktokTopVideosViews": { "type": [ "integer", "null" ], "minimum": 0, "description": "View count across the track's top TikTok videos." }, "youtubeComments": { "type": [ "integer", "null" ], "minimum": 0, "description": "YouTube comment count." }, "youtubeLikes": { "type": [ "integer", "null" ], "minimum": 0, "description": "YouTube like count." }, "youtubeViews": { "type": [ "integer", "null" ], "minimum": 0, "description": "YouTube view count." } }, "description": "Cross-platform metric snapshots hydrated from per-target cache rows." }, "isChartGenre": { "type": [ "boolean", "null" ], "description": "True when the track's genre matches the chart's genre filter." } } } } }, "required": [ "obj" ] }, "examples": { "default": { "value": { "obj": [ { "entityId": 27599255, "targetId": "uLHqpjW3aDs", "name": "Roddy Ricch - The Box [Official Audio]", "rank": 1, "chartedDate": "2026-02-06", "country": "US", "imageUrl": null, "rankDiff": 0, "artists": [ { "id": 839964, "name": "Roddy Ricch", "code2": "US", "imageUrl": null, "careerStage": "mainstream" } ], "album": { "id": null, "name": "The Box", "label": null, "releaseDate": null }, "isrc": "USAT21906978", "externalId": "uLHqpjW3aDs", "targetExtras": { "youtubeViews": 20500000 }, "genre": "hip-hop/rap", "isChartGenre": false } ] } } } } } } } } }, "/api/charts/youtube/tracks": { "get": { "summary": "Get YouTube Top-Track Chart (weekly)", "tags": [ "Charts" ], "operationId": "getYoutubeTrackCharts", "description": "Return the YouTube weekly top-track chart for a given `country_code` and `date`. Each row merges track-basic-info with the chart row and carries both `rankStats` (rank history) and `viewStats` (views history). Data is updated weekly on Thursdays.", "parameters": [ { "name": "country_code", "in": "query", "schema": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB')." }, "required": true, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB').", "examples": { "default": { "value": "US" } } }, { "name": "date", "in": "query", "schema": { "anyOf": [ { "type": "string", "format": "date-time", "x-required": true } ], "description": "Date for the time-slice (YYYY-MM-DD). Required unless `latest=true`." }, "required": false, "description": "Date for the time-slice (YYYY-MM-DD). Required unless `latest=true`." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, "required": false, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, { "name": "latest", "in": "query", "schema": { "type": "boolean", "description": "If true, use the most recently available date and ignore `date`." }, "required": false, "description": "If true, use the most recently available date and ignore `date`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "object", "properties": { "length": { "type": "integer", "minimum": 0, "description": "Number of chart rows in `data`." }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "string", "null" ], "description": "YouTube video ID." }, "youtube_track_id": { "type": [ "string", "null" ], "description": "YouTube track ID." }, "youtube_artist": { "type": [ "string", "null" ], "description": "YouTube artist channel link/ID." }, "youtube_artist_name": { "type": [ "string", "null" ], "description": "YouTube artist name." }, "youtube_artist_cm_artist": { "type": [ "integer", "null" ], "description": "Chartmetric artist ID for the YouTube artist." }, "artist_name": { "type": [ "string", "null" ], "description": "Track artist name." }, "youtube_artist_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "YouTube artist IDs." }, "youtube_track_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "YouTube track IDs." }, "youtube_artist_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "YouTube artist names." }, "position": { "type": [ "integer", "null" ], "description": "Current chart position (1 = top)." }, "rank": { "type": [ "integer", "null" ], "description": "Current chart rank. Same value as `position`." }, "view_count": { "type": [ "integer", "null" ], "minimum": 0, "description": "Total view count." }, "added_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp the track was added to the chart." }, "upload_date": { "type": [ "string", "null" ], "format": "date-time", "description": "YouTube upload date." }, "license": { "type": [ "string", "null" ], "description": "YouTube license owner (e.g. `WMG`, `UMG`)." }, "velocity": { "type": [ "number", "null" ], "format": "float", "description": "Rank-velocity signal (positive = climbing)." }, "pre_rank": { "type": [ "integer", "null" ], "description": "Position on the previous chart period." }, "peak_rank": { "type": [ "integer", "null" ], "description": "Best (lowest-numbered) rank reached." }, "peak_date": { "type": [ "string", "null" ], "format": "date-time", "description": "Date `peak_rank` was achieved." }, "time_on_chart": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "nullable": true, "description": "Length of time on the chart (integer count of periods or duration string)." }, "type": { "type": [ "integer", "null" ], "description": "Chart sub-type code (legacy)." }, "raw_data": { "description": "Raw chart row payload (legacy passthrough)." }, "rankStats": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "rank": { "type": [ "integer", "null" ], "description": "Rank at `timestp` (1 = top)." }, "timestp": { "anyOf": [ { "type": [ "string", "null" ], "format": "date-time" } ], "description": "Timestamp of the rank sample." } } }, "description": "Historical rank samples." }, "viewStats": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "views": { "type": [ "integer", "null" ], "minimum": 0, "description": "View count at `timestp`." }, "timestp": { "anyOf": [ { "type": [ "string", "null" ], "format": "date-time" } ], "description": "Timestamp of the view-count sample." } } }, "description": "Historical view-count samples." }, "cm_track": { "type": [ "integer", "null" ], "description": "Chartmetric track ID." }, "name": { "type": [ "string", "null" ], "description": "Track name." }, "isrc": { "type": [ "string", "null" ], "description": "International Standard Recording Code." }, "image_url": { "type": [ "string", "null" ], "description": "Track or album cover image URL." }, "cm_artist": { "anyOf": [ { "type": "integer" }, { "type": "array", "items": { "type": [ "integer", "null" ] } } ], "nullable": true, "description": "Chartmetric artist ID(s) — single value or array depending on platform." }, "artist_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Track artist names." }, "code2s": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Country codes per artist (ISO 3166-1 alpha-2)." }, "artist_images": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Artist profile image URLs." }, "artist_covers": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Artist cover image URLs." }, "album_ids": { "type": [ "array", "null" ], "items": { "type": [ "integer", "null" ] }, "description": "Chartmetric album IDs." }, "album_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Album names." }, "album_upc": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Album UPC values." }, "album_label": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Record labels for the album(s)." }, "release_dates": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Album release dates." }, "artists": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ], "description": "Chartmetric artist ID." }, "name": { "type": [ "string", "null" ], "description": "Artist name." }, "code2": { "type": [ "string", "null" ], "description": "Artist country code (ISO 3166-1 alpha-2)." }, "image_url": { "type": [ "string", "null" ], "description": "Artist image URL." }, "career_stage": { "type": [ "string", "null" ], "description": "Artist career stage (e.g. `undiscovered`, `developing`, `mid-level`, `mainstream`, `superstar`, `legendary`)." } } }, "description": "Normalized artist info objects for the track." }, "album": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": {} } }, { "type": "object", "properties": {} } ], "nullable": true, "description": "Album info object (or array of objects) associated with the track." }, "duration_ms": { "type": [ "integer", "null" ], "description": "Track duration in milliseconds." }, "explicit": { "type": [ "boolean", "null" ], "description": "Whether the track is flagged as explicit." }, "preview_url": { "type": [ "string", "null" ], "description": "Audio preview URL." }, "track_genre": { "anyOf": [ { "type": "string" }, { "type": "array", "items": {} } ], "nullable": true, "description": "Track genre(s) — string or array of strings." }, "spotify_popularity": { "type": [ "integer", "null" ], "description": "Spotify popularity score (0–100)." } } }, "description": "Chart rows ordered by rank (1 = highest)." } }, "required": [ "length", "data" ] } }, "required": [ "obj" ] }, "examples": { "default": { "value": { "obj": { "length": 1, "data": [ { "id": "uLHqpjW3aDs", "youtube_track_id": "uLHqpjW3aDs", "name": "Roddy Ricch - The Box [Official Audio]", "isrc": "USAT21906978", "youtube_artist": "/g/11fhvxdh1f", "image_url": null, "cm_track": 27599255, "upload_date": "2019-12-06T05:05:28.000Z", "license": "WMG", "album_names": [ "The Box" ], "youtube_artist_names": [ "Roddy Ricch" ], "cm_artist": [ 839964 ], "artist_names": [ "Roddy Ricch" ], "code2s": [ "US" ], "artist_images": [ "https://lh3.googleusercontent.com/a-/AAuE7mD9mk4b9HXoY3SQHbXScUGwoLs_pDjXrA_rG3KP=w60-h60-l90-rj" ], "artist_covers": [ null ], "youtube_artist_ids": [ "/g/11fhvxdh1f" ], "youtube_track_ids": [ "uLHqpjW3aDs" ], "artist_name": "Roddy Ricch", "position": 1, "added_at": "2020-02-06T00:00:00.000Z", "view_count": 20500000, "raw_data": null, "velocity": 0, "pre_rank": 1, "peak_rank": 1, "peak_date": "2020-01-09T00:00:00.000Z", "time_on_chart": "8", "rankStats": [ { "rank": 1, "timestp": "2020-01-30T00:00:00.000Z" } ], "viewStats": [ { "views": 18400000, "timestp": "2020-01-30T00:00:00.000Z" } ] } ] } } } } } } } } } }, "/api/charts/youtube/videos": { "get": { "summary": "Get YouTube Top-Video Chart (weekly)", "tags": [ "Charts" ], "operationId": "getYoutubeVideoCharts", "description": "Return the YouTube weekly top-video chart for a given `country_code` and `date`. Each row merges video-basic-info with the chart row and carries both `rankStats` and `viewStats` histories. Data is updated weekly on Thursdays.", "parameters": [ { "name": "country_code", "in": "query", "schema": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB')." }, "required": true, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB').", "examples": { "default": { "value": "US" } } }, { "name": "date", "in": "query", "schema": { "anyOf": [ { "type": "string", "format": "date-time", "x-required": true } ], "description": "Date for the time-slice (YYYY-MM-DD). Required unless `latest=true`." }, "required": false, "description": "Date for the time-slice (YYYY-MM-DD). Required unless `latest=true`." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, "required": false, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, { "name": "latest", "in": "query", "schema": { "type": "boolean", "description": "If true, use the most recently available date and ignore `date`." }, "required": false, "description": "If true, use the most recently available date and ignore `date`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "object", "properties": { "length": { "type": "integer", "minimum": 0, "description": "Number of chart rows in `data`." }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "nullable": true, "description": "YouTube video ID." }, "youtube": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Internal YouTube chart row ID." }, "position": { "type": [ "integer", "null" ], "description": "Current chart position (1 = top)." }, "rank": { "type": [ "integer", "null" ], "description": "Current chart rank. Same value as `position`." }, "view_count": { "type": [ "integer", "null" ], "minimum": 0, "description": "Total view count." }, "added_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp the row was added to the chart." }, "upload_date": { "type": [ "string", "null" ], "format": "date-time", "description": "YouTube upload date." }, "license": { "type": [ "string", "null" ], "description": "YouTube license owner (e.g. `WMG`, `UMG`)." }, "velocity": { "type": [ "number", "null" ], "format": "float", "description": "Rank-velocity signal (positive = climbing)." }, "pre_rank": { "type": [ "integer", "null" ], "description": "Position on the previous chart period." }, "peak_rank": { "type": [ "integer", "null" ], "description": "Best (lowest-numbered) rank reached." }, "peak_date": { "type": [ "string", "null" ], "format": "date-time", "description": "Date `peak_rank` was achieved." }, "time_on_chart": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "nullable": true, "description": "Length of time on the chart (integer count of periods or duration string)." }, "rankStats": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "rank": { "type": [ "integer", "null" ], "description": "Rank at `timestp` (1 = top)." }, "timestp": { "anyOf": [ { "type": [ "string", "null" ], "format": "date-time" } ], "description": "Timestamp of the rank sample." } } }, "description": "Historical rank samples." }, "viewStats": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "views": { "type": [ "integer", "null" ], "minimum": 0, "description": "View count at `timestp`." }, "timestp": { "anyOf": [ { "type": [ "string", "null" ], "format": "date-time" } ], "description": "Timestamp of the view-count sample." } } }, "description": "Historical view-count samples." }, "cm_track": { "type": [ "integer", "null" ], "description": "Chartmetric track ID." }, "name": { "type": [ "string", "null" ], "description": "Track name." }, "isrc": { "type": [ "string", "null" ], "description": "International Standard Recording Code." }, "image_url": { "type": [ "string", "null" ], "description": "Track or album cover image URL." }, "cm_artist": { "anyOf": [ { "type": "integer" }, { "type": "array", "items": { "type": [ "integer", "null" ] } } ], "nullable": true, "description": "Chartmetric artist ID(s) — single value or array depending on platform." }, "artist_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Track artist names." }, "code2s": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Country codes per artist (ISO 3166-1 alpha-2)." }, "artist_images": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Artist profile image URLs." }, "artist_covers": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Artist cover image URLs." }, "album_ids": { "type": [ "array", "null" ], "items": { "type": [ "integer", "null" ] }, "description": "Chartmetric album IDs." }, "album_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Album names." }, "album_upc": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Album UPC values." }, "album_label": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Record labels for the album(s)." }, "release_dates": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Album release dates." }, "artists": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ], "description": "Chartmetric artist ID." }, "name": { "type": [ "string", "null" ], "description": "Artist name." }, "code2": { "type": [ "string", "null" ], "description": "Artist country code (ISO 3166-1 alpha-2)." }, "image_url": { "type": [ "string", "null" ], "description": "Artist image URL." }, "career_stage": { "type": [ "string", "null" ], "description": "Artist career stage (e.g. `undiscovered`, `developing`, `mid-level`, `mainstream`, `superstar`, `legendary`)." } } }, "description": "Normalized artist info objects for the track." }, "album": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": {} } }, { "type": "object", "properties": {} } ], "nullable": true, "description": "Album info object (or array of objects) associated with the track." }, "duration_ms": { "type": [ "integer", "null" ], "description": "Track duration in milliseconds." }, "explicit": { "type": [ "boolean", "null" ], "description": "Whether the track is flagged as explicit." }, "preview_url": { "type": [ "string", "null" ], "description": "Audio preview URL." }, "track_genre": { "anyOf": [ { "type": "string" }, { "type": "array", "items": {} } ], "nullable": true, "description": "Track genre(s) — string or array of strings." }, "spotify_popularity": { "type": [ "integer", "null" ], "description": "Spotify popularity score (0–100)." } } }, "description": "Chart rows ordered by rank (1 = highest)." } }, "required": [ "length", "data" ] } }, "required": [ "obj" ] }, "examples": { "default": { "value": { "obj": { "length": 1, "data": [ { "id": "uLHqpjW3aDs", "name": "Roddy Ricch - The Box [Official Video]", "isrc": "USAT21906978", "image_url": null, "cm_track": 27599255, "youtube": 27599255, "position": 1, "view_count": 20500000, "added_at": "2020-02-06T00:00:00.000Z", "upload_date": "2019-12-06T05:05:28.000Z", "velocity": 0, "pre_rank": 1, "peak_rank": 1, "peak_date": "2020-01-09T00:00:00.000Z", "time_on_chart": "8", "rankStats": [ { "rank": 1, "timestp": "2020-01-30T00:00:00.000Z" } ], "viewStats": [ { "views": 18400000, "timestp": "2020-01-30T00:00:00.000Z" } ] } ] } } } } } } } } } }, "/api/charts/youtube/trends": { "get": { "summary": "Get YouTube Trend Chart (weekly)", "tags": [ "Charts" ], "operationId": "getYoutubeTrendCharts", "description": "Return the YouTube trend (trending) chart for a given `country_code` and `date`. Rows are projected by `ChartView.getYoutubeTrendChart`, which forwards track-basic-info + chart-info + per-track `rankStats`. Data is updated weekly on Thursdays.", "parameters": [ { "name": "country_code", "in": "query", "schema": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB')." }, "required": true, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB').", "examples": { "default": { "value": "US" } } }, { "name": "date", "in": "query", "schema": { "anyOf": [ { "type": "string", "format": "date-time", "x-required": true } ], "description": "Date for the time-slice (YYYY-MM-DD). Required unless `latest=true`." }, "required": false, "description": "Date for the time-slice (YYYY-MM-DD). Required unless `latest=true`." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, "required": false, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, { "name": "latest", "in": "query", "schema": { "type": "boolean", "description": "If true, use the most recently available date and ignore `date`." }, "required": false, "description": "If true, use the most recently available date and ignore `date`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "object", "properties": { "length": { "type": "integer", "minimum": 0, "description": "Number of chart rows in `data`." }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "nullable": true, "description": "Chart row ID (legacy)." }, "youtube": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Internal YouTube row ID." }, "youtube_video_id": { "type": [ "string", "null" ], "description": "YouTube video ID." }, "name": { "type": [ "string", "null" ], "description": "Track name." }, "artist_name": { "type": [ "string", "null" ], "description": "Track artist name." }, "youtube_artist": { "type": [ "string", "null" ], "description": "YouTube artist channel link/ID." }, "youtube_artist_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "YouTube artist names." }, "cm_artist": { "anyOf": [ { "type": "integer" }, { "type": "array", "items": { "type": [ "integer", "null" ] } } ], "nullable": true, "description": "Chartmetric artist ID(s)." }, "artist_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Track artist names." }, "artists": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ], "description": "Chartmetric artist ID." }, "name": { "type": [ "string", "null" ], "description": "Artist name." }, "code2": { "type": [ "string", "null" ], "description": "Artist country code (ISO 3166-1 alpha-2)." } } }, "description": "Normalized artist info objects." }, "isrc": { "type": [ "string", "null" ], "description": "International Standard Recording Code." }, "cm_track": { "type": [ "integer", "null" ], "description": "Chartmetric track ID." }, "duration_ms": { "type": [ "integer", "null" ], "description": "Track duration in milliseconds." }, "explicit": { "type": [ "boolean", "null" ], "description": "Whether the track is flagged as explicit." }, "composer_name": { "type": [ "string", "null" ], "description": "Composer name(s)." }, "upload_date": { "type": [ "string", "null" ], "format": "date-time", "description": "YouTube upload date." }, "added_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp the row was added to the chart." }, "peak_date": { "type": [ "string", "null" ], "format": "date-time", "description": "Date `peak_rank` was achieved." }, "image_url": { "type": [ "string", "null" ], "description": "Track image URL." }, "preview_url": { "type": [ "string", "null" ], "description": "Audio preview URL." }, "position": { "type": [ "integer", "null" ], "description": "Current chart position (1 = top)." }, "velocity": { "type": [ "number", "null" ], "format": "float", "description": "Rank-velocity signal (positive = climbing)." }, "pre_rank": { "type": [ "integer", "null" ], "description": "Position on the previous chart period." }, "peak_rank": { "type": [ "integer", "null" ], "description": "Best (lowest-numbered) rank reached." }, "time_on_chart": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "nullable": true, "description": "Length of time on the chart (integer count of periods or duration string)." }, "raw_data": { "description": "Raw chart row payload (legacy passthrough)." }, "album_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Album names." }, "album": { "description": "Album info (object or array; permissive shape)." }, "album_ids": { "type": [ "array", "null" ], "items": { "type": [ "integer", "null" ] }, "description": "Chartmetric album IDs." }, "album_upc": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Album UPC values." }, "album_label": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Record labels for the album(s)." }, "genre": { "type": [ "string", "null" ], "description": "Chart genre." }, "genre_smart_ordered": { "type": [ "array", "null" ], "items": { "type": "object", "properties": {} }, "description": "Smart-ordered genre tags from Chartmetric's genre classification." }, "tags": { "anyOf": [ { "type": "string" }, { "type": "array", "items": {} } ], "nullable": true, "description": "YouTube video tags." }, "track_genre": { "anyOf": [ { "type": "string" }, { "type": "array", "items": {} } ], "nullable": true, "description": "Track genre(s)." }, "spotify_popularity": { "type": [ "integer", "null" ], "description": "Spotify popularity score (0–100)." }, "latest": { "type": [ "object", "null" ], "properties": {}, "description": "Latest snapshot of per-row metrics." }, "score": { "type": [ "number", "null" ], "format": "float", "description": "Trend score for the chart row." }, "license": { "type": [ "string", "null" ], "description": "YouTube license owner (e.g. `WMG`)." }, "code2s": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Country codes per artist (ISO 3166-1 alpha-2)." }, "artist_images": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Artist profile image URLs." }, "artist_covers": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Artist cover image URLs." }, "youtube_artist_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "YouTube artist IDs." }, "youtube_track_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "YouTube track IDs." }, "release_dates": { "type": [ "array", "null" ], "items": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true }, "description": "Album release dates." }, "doc_id": { "type": [ "string", "null" ], "description": "Internal document ID for the chart row." }, "batch_ids": { "description": "Internal batch correlation IDs (legacy passthrough)." }, "rankStats": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "rank": { "type": [ "integer", "null" ], "description": "Rank at `timestp` (1 = top)." }, "views": { "type": [ "integer", "null" ], "minimum": 0, "description": "View count at `timestp`." }, "timestp": { "anyOf": [ { "type": [ "string", "null" ], "format": "date-time" } ], "description": "Timestamp of the rank sample." } } }, "description": "Historical rank + view samples." } } }, "description": "Chart rows ordered by rank (1 = highest)." } }, "required": [ "length", "data" ] } }, "required": [ "obj" ] }, "examples": { "default": { "value": { "obj": { "length": 1, "data": [ { "id": 27599255, "youtube": 27599255, "youtube_video_id": "uLHqpjW3aDs", "name": "Roddy Ricch - The Box [Official Audio]", "artist_name": "Roddy Ricch", "youtube_artist": "/g/11fhvxdh1f", "youtube_artist_names": [ "Roddy Ricch" ], "cm_artist": 839964, "artist_names": [ "Roddy Ricch" ], "isrc": "USAT21906978", "cm_track": 27599255, "position": 1, "velocity": 0, "pre_rank": 1, "peak_rank": 1, "peak_date": "2020-01-09T00:00:00.000Z", "added_at": "2020-02-06T00:00:00.000Z", "upload_date": "2019-12-06T05:05:28.000Z", "time_on_chart": "8", "image_url": null, "code2s": [ "US" ], "rankStats": [ { "rank": 1, "views": 18400000, "timestp": "2020-01-30T00:00:00.000Z" } ] } ] } } } } } } } } } }, "/api/charts/youtube/artists": { "get": { "summary": "Get YouTube Top-Artist Chart (weekly)", "tags": [ "Charts" ], "operationId": "getYoutubeArtistCharts", "description": "Return the YouTube weekly top-artist chart for a given `country_code` and `date`. Each row carries the chart row + per-artist `rankStats` and `viewStats` histories, plus `image_url` hydrated from `Artist.getBasicInfoBatch`. Data is updated weekly on Thursdays.", "parameters": [ { "name": "country_code", "in": "query", "schema": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB')." }, "required": true, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB').", "examples": { "default": { "value": "US" } } }, { "name": "date", "in": "query", "schema": { "anyOf": [ { "type": "string", "format": "date-time", "x-required": true } ], "description": "Date for the time-slice (YYYY-MM-DD). Required unless `latest=true`." }, "required": false, "description": "Date for the time-slice (YYYY-MM-DD). Required unless `latest=true`." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, "required": false, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, { "name": "latest", "in": "query", "schema": { "type": "boolean", "description": "If true, use the most recently available date and ignore `date`." }, "required": false, "description": "If true, use the most recently available date and ignore `date`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "object", "properties": { "length": { "type": "integer", "minimum": 0, "description": "Number of chart rows in `data`." }, "data": { "type": "array", "items": { "type": "object", "properties": { "cm_artist": { "type": [ "integer", "null" ], "description": "Chartmetric artist ID." }, "youtube_artist": { "type": [ "string", "null" ], "description": "YouTube artist channel link/ID." }, "name": { "type": [ "string", "null" ], "description": "Artist name." }, "image_url": { "type": [ "string", "null" ], "description": "Artist image URL." }, "rank": { "type": [ "integer", "null" ], "description": "Current chart rank (1 = top)." }, "position": { "type": [ "integer", "null" ], "description": "Current chart position. Same value as `rank`." }, "view_count": { "type": [ "integer", "null" ], "minimum": 0, "description": "Total view count across the artist's YouTube channel." }, "subscriber_count": { "type": [ "integer", "null" ], "minimum": 0, "description": "YouTube subscriber count." }, "added_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp the artist was added to the chart." }, "velocity": { "type": [ "number", "null" ], "format": "float", "description": "Rank-velocity signal (positive = climbing)." }, "pre_rank": { "type": [ "integer", "null" ], "description": "Position on the previous chart period." }, "peak_rank": { "type": [ "integer", "null" ], "description": "Best (lowest-numbered) rank reached." }, "peak_date": { "type": [ "string", "null" ], "format": "date-time", "description": "Date `peak_rank` was achieved." }, "time_on_chart": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "nullable": true, "description": "Length of time on the chart (integer count of periods or duration string)." }, "rankStats": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "rank": { "type": [ "integer", "null" ], "description": "Rank at `timestp` (1 = top)." }, "timestp": { "anyOf": [ { "type": [ "string", "null" ], "format": "date-time" } ], "description": "Timestamp of the rank sample." } } }, "description": "Historical rank samples." }, "viewStats": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "views": { "type": [ "integer", "null" ], "minimum": 0, "description": "View count at `timestp`." }, "timestp": { "anyOf": [ { "type": [ "string", "null" ], "format": "date-time" } ], "description": "Timestamp of the view-count sample." } } }, "description": "Historical view-count samples." } } }, "description": "Chart rows ordered by rank (1 = highest)." } }, "required": [ "length", "data" ] } }, "required": [ "obj" ] }, "examples": { "default": { "value": { "obj": { "length": 1, "data": [ { "cm_artist": 839964, "youtube_artist": "/g/11fhvxdh1f", "name": "Roddy Ricch", "image_url": "https://lh3.googleusercontent.com/a-/AAuE7mD9mk4b9HXoY3SQHbXScUGwoLs_pDjXrA_rG3KP=w60-h60-l90-rj", "rank": 1, "added_at": "2020-02-06T00:00:00.000Z", "velocity": 0, "pre_rank": 1, "peak_rank": 1, "peak_date": "2020-01-09T00:00:00.000Z", "time_on_chart": "8", "rankStats": [ { "rank": 1, "timestp": "2020-01-30T00:00:00.000Z" } ], "viewStats": [ { "views": 18400000, "timestp": "2020-01-30T00:00:00.000Z" } ] } ] } } } } } } } } } }, "/api/charts/airplay/tracks": { "get": { "summary": "Airplay Track Charts", "tags": [ "Charts" ], "operationId": "getAirplayTrackCharts", "description": "ACR airplay track charts. Handler builds the SQL table name from `duration` (`acr_daily_track_chart` / `acr_weekly_track_chart`) and optional `cityId` variant. Merges cross-platform track metadata and batched historical `rankStats` from `QUERY_GET_TRACK_RANKINGS.ACR_BATCH`.", "parameters": [ { "name": "date", "in": "query", "schema": { "type": "string", "format": "date-time", "description": "Charting date (`YYYY-MM-DD`). Defaults to the latest available chart when omitted." }, "required": false, "description": "Charting date (`YYYY-MM-DD`). Defaults to the latest available chart when omitted." }, { "name": "since", "in": "query", "schema": { "anyOf": [ { "type": "string", "format": "date-time", "x-required": true } ], "description": "Lower bound of the date range (YYYY-MM-DD). Required unless `latest=true`." }, "required": false, "description": "Lower bound of the date range (YYYY-MM-DD). Required unless `latest=true`." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "description": "Maximum entries returned per request (max 500)." }, "required": false, "description": "Maximum entries returned per request (max 500)." }, { "name": "duration", "in": "query", "schema": { "type": "string", "enum": [ "daily", "weekly", "monthly", "semi-yearly", "yearly", "all_time" ], "description": "Chart duration (e.g. `daily`, `weekly`, `monthly`)." }, "required": true, "description": "Chart duration (e.g. `daily`, `weekly`, `monthly`).", "examples": { "default": { "value": "daily" } } }, { "name": "country_code", "in": "query", "schema": { "type": "string", "enum": [ "AF", "NL", "AN", "AL", "DZ", "AS", "AD", "AO", "AI", "AG", "AE", "AR", "AM", "AW", "AU", "AZ", "BS", "BH", "BD", "BB", "BE", "BZ", "BJ", "BM", "BT", "BO", "BA", "BW", "BR", "GB", "VG", "BN", "BG", "BF", "BI", "KY", "CL", "CK", "CR", "DJ", "DM", "DO", "EC", "EG", "SV", "ER", "ES", "ZA", "ET", "FK", "FJ", "PH", "FO", "GA", "GM", "GE", "GH", "GI", "GD", "GL", "GP", "GU", "GT", "GN", "GW", "GY", "HT", "HN", "HK", "SJ", "ID", "IN", "IQ", "IR", "IE", "IS", "IL", "IT", "TP", "AT", "JM", "JP", "YE", "JO", "CX", "YU", "KH", "CM", "CA", "CV", "KZ", "KE", "CF", "CN", "KG", "KI", "CO", "KM", "CG", "CD", "CC", "KP", "KR", "GR", "HR", "CU", "KW", "CY", "LA", "LV", "LS", "LB", "LR", "LY", "LI", "LT", "LU", "EH", "MO", "MG", "MK", "MW", "MV", "MY", "ML", "MT", "MA", "MH", "MQ", "MR", "MU", "YT", "MX", "FM", "MD", "MC", "MN", "MS", "MZ", "MM", "NA", "NR", "NP", "NI", "NE", "NG", "NU", "NF", "NO", "CI", "OM", "PK", "PW", "PA", "PG", "PY", "PE", "PN", "MP", "PT", "PR", "PL", "GQ", "QA", "FR", "GF", "PF", "RE", "RO", "RW", "SE", "SH", "KN", "LC", "VC", "PM", "DE", "SB", "ZM", "WS", "SM", "ST", "SA", "SN", "SC", "SL", "SG", "SK", "SI", "SO", "LK", "SD", "FI", "SR", "SZ", "CH", "SY", "TJ", "TW", "TZ", "DK", "TH", "TG", "TK", "TO", "TT", "TD", "CZ", "TN", "TR", "TM", "TC", "TV", "UG", "UA", "HU", "UY", "NC", "NZ", "UZ", "BY", "WF", "VU", "VA", "VE", "RU", "VN", "EE", "US", "VI", "ZW", "PS", "AQ", "BV", "IO", "GS", "HM", "TF", "UM", "GLOBAL" ], "description": "Airplay country code; only the ACR-supported countries are accepted. Defaults to 'GLOBAL'.", "default": "GLOBAL" }, "required": false, "description": "Airplay country code; only the ACR-supported countries are accepted. Defaults to 'GLOBAL'." }, { "name": "latest", "in": "query", "schema": { "type": "boolean", "description": "If true, use the most recently available date and ignore `since`." }, "required": false, "description": "If true, use the most recently available date and ignore `since`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "object", "properties": { "length": { "type": [ "integer", "null" ], "description": "Number of chart rows in `data`." }, "data": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 2147483647 }, { "type": "string" } ], "nullable": true, "description": "Platform-side track ID (or Chartmetric ID for ISRC-keyed lookups)." }, "name": { "type": [ "string", "null" ], "description": "Track name." }, "isrc": { "type": [ "string", "null" ], "description": "International Standard Recording Code." }, "image_url": { "type": [ "string", "null" ], "description": "Track or album cover image URL." }, "description": { "type": [ "string", "null" ], "description": "Track description (free-text metadata)." }, "tags": { "type": [ "string", "null" ], "description": "Comma-separated genre tags for the track." }, "cm_track": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Chartmetric track ID." }, "cm_artist": { "type": [ "array", "null" ], "items": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647 }, "description": "Chartmetric artist IDs of the track artists." }, "artist_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Track artist names." }, "code2s": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Country codes per artist (ISO 3166-1 alpha-2)." }, "artist_images": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Artist profile image URLs." }, "artist_covers": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Artist cover image URLs." }, "spotify_track_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Spotify track IDs." }, "spotify_album_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Spotify album IDs." }, "spotify_duration_ms": { "type": [ "integer", "null" ], "description": "Track duration on Spotify in milliseconds." }, "itunes_track_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "iTunes track IDs." }, "itunes_album_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "iTunes album IDs." }, "itunes_artist_ids": { "type": [ "array", "null" ], "items": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "nullable": true }, "description": "iTunes artist IDs." }, "itunes_artist_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "iTunes artist names." }, "storefronts": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "iTunes/Apple Music storefront codes (ISO 3166-1 alpha-2 lowercased)." }, "deezer_track_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Deezer track IDs." }, "deezer_album_ids": { "type": [ "array", "null" ], "items": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true }, "description": "Deezer album IDs." }, "deezer_duration": { "type": [ "integer", "null" ], "description": "Track duration on Deezer in seconds." }, "amazon_track_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Amazon track IDs." }, "amazon_album_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Amazon album IDs." }, "album_ids": { "type": [ "array", "null" ], "items": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 2147483647 }, { "type": "string" } ], "nullable": true }, "description": "Chartmetric album IDs." }, "album_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Album names." }, "album_upc": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Album UPC values." }, "album_label": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Record labels for the album(s)." }, "release_dates": { "type": [ "array", "null" ], "items": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string" } ], "nullable": true }, "description": "Album release dates." }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string" } ], "nullable": true, "description": "Track-record creation timestamp." }, "modified_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string" } ], "nullable": true, "description": "Track-record last-modified timestamp." }, "rank": { "type": [ "integer", "null" ], "description": "Current chart rank (1 = top)." }, "pre_rank": { "type": [ "integer", "null" ], "description": "Position on the previous chart period." }, "peak_rank": { "type": [ "integer", "null" ], "description": "Best (lowest-numbered) rank reached." }, "peak_date": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string" } ], "nullable": true, "description": "Date `peak_rank` was achieved." }, "added_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string" } ], "nullable": true, "description": "Timestamp the row was added to the chart." }, "velocity": { "type": [ "number", "null" ], "format": "float", "description": "Rank-velocity signal (positive = climbing)." }, "time_on_chart": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Length of time on the chart." }, "code2": { "type": [ "string", "null" ], "description": "Chart country code (ISO 3166-1 alpha-2 or `GLOBAL`)." }, "city_id": { "type": [ "integer", "null" ], "description": "Chartmetric city ID when the chart is city-scoped." }, "plays": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Total airplay plays in the chart window." }, "count": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Daily airplay play count." }, "weekly_count": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Weekly airplay play count." }, "rankStats": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "rank": { "type": [ "integer", "null" ], "description": "Rank at `timestp` (1 = top)." }, "plays": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Play count at `timestp` (ACR airplay)." }, "timestp": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string" } ], "nullable": true, "description": "Timestamp of the sample." } } }, "description": "Historical rank + plays samples." } } }, "description": "Chart rows ordered by rank (1 = highest)." } } } }, "additionalProperties": false } } } } } } }, "/api/charts/airplay/artists": { "get": { "summary": "Airplay Artist Charts", "tags": [ "Charts" ], "operationId": "getAirplayArtistCharts", "description": "ACR airplay artist charts. Duration and optional `cityId` select the source `acr_*_artist_*chart` table. Merges `Artist.getBasicInfoBatch(artistIds)` plus batched historical `rankStats` from `QUERY_GET_USER_RANKINGS.ACR_BATCH`.", "parameters": [ { "name": "date", "in": "query", "schema": { "type": "string", "format": "date-time", "description": "Charting date (`YYYY-MM-DD`). Defaults to the latest available chart when omitted." }, "required": false, "description": "Charting date (`YYYY-MM-DD`). Defaults to the latest available chart when omitted." }, { "name": "since", "in": "query", "schema": { "anyOf": [ { "type": "string", "format": "date-time", "x-required": true } ], "description": "Lower bound of the date range (YYYY-MM-DD). Required unless `latest=true`." }, "required": false, "description": "Lower bound of the date range (YYYY-MM-DD). Required unless `latest=true`." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "description": "Maximum entries returned per request (max 500)." }, "required": false, "description": "Maximum entries returned per request (max 500)." }, { "name": "duration", "in": "query", "schema": { "type": "string", "enum": [ "daily", "weekly" ], "description": "Chart duration; only `daily` and `weekly` have a backing ACR artist chart table." }, "required": true, "description": "Chart duration; only `daily` and `weekly` have a backing ACR artist chart table.", "examples": { "default": { "value": "daily" } } }, { "name": "country_code", "in": "query", "schema": { "type": "string", "enum": [ "AF", "NL", "AN", "AL", "DZ", "AS", "AD", "AO", "AI", "AG", "AE", "AR", "AM", "AW", "AU", "AZ", "BS", "BH", "BD", "BB", "BE", "BZ", "BJ", "BM", "BT", "BO", "BA", "BW", "BR", "GB", "VG", "BN", "BG", "BF", "BI", "KY", "CL", "CK", "CR", "DJ", "DM", "DO", "EC", "EG", "SV", "ER", "ES", "ZA", "ET", "FK", "FJ", "PH", "FO", "GA", "GM", "GE", "GH", "GI", "GD", "GL", "GP", "GU", "GT", "GN", "GW", "GY", "HT", "HN", "HK", "SJ", "ID", "IN", "IQ", "IR", "IE", "IS", "IL", "IT", "TP", "AT", "JM", "JP", "YE", "JO", "CX", "YU", "KH", "CM", "CA", "CV", "KZ", "KE", "CF", "CN", "KG", "KI", "CO", "KM", "CG", "CD", "CC", "KP", "KR", "GR", "HR", "CU", "KW", "CY", "LA", "LV", "LS", "LB", "LR", "LY", "LI", "LT", "LU", "EH", "MO", "MG", "MK", "MW", "MV", "MY", "ML", "MT", "MA", "MH", "MQ", "MR", "MU", "YT", "MX", "FM", "MD", "MC", "MN", "MS", "MZ", "MM", "NA", "NR", "NP", "NI", "NE", "NG", "NU", "NF", "NO", "CI", "OM", "PK", "PW", "PA", "PG", "PY", "PE", "PN", "MP", "PT", "PR", "PL", "GQ", "QA", "FR", "GF", "PF", "RE", "RO", "RW", "SE", "SH", "KN", "LC", "VC", "PM", "DE", "SB", "ZM", "WS", "SM", "ST", "SA", "SN", "SC", "SL", "SG", "SK", "SI", "SO", "LK", "SD", "FI", "SR", "SZ", "CH", "SY", "TJ", "TW", "TZ", "DK", "TH", "TG", "TK", "TO", "TT", "TD", "CZ", "TN", "TR", "TM", "TC", "TV", "UG", "UA", "HU", "UY", "NC", "NZ", "UZ", "BY", "WF", "VU", "VA", "VE", "RU", "VN", "EE", "US", "VI", "ZW", "PS", "AQ", "BV", "IO", "GS", "HM", "TF", "UM", "GLOBAL" ], "description": "Airplay country code; only the ACR-supported countries are accepted. Defaults to 'GLOBAL'.", "default": "GLOBAL" }, "required": false, "description": "Airplay country code; only the ACR-supported countries are accepted. Defaults to 'GLOBAL'." }, { "name": "latest", "in": "query", "schema": { "type": "boolean", "description": "If true, use the most recently available date and ignore `since`." }, "required": false, "description": "If true, use the most recently available date and ignore `since`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "object", "properties": { "length": { "type": [ "integer", "null" ], "description": "Number of chart rows in `data`." }, "data": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "rank": { "type": [ "integer", "null" ], "description": "Current chart rank (1 = top)." }, "pre_rank": { "type": [ "integer", "null" ], "description": "Position on the previous chart period." }, "peak_rank": { "type": [ "integer", "null" ], "description": "Best (lowest-numbered) rank reached." }, "peak_date": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string" } ], "nullable": true, "description": "Date `peak_rank` was achieved." }, "added_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string" } ], "nullable": true, "description": "Timestamp the row was added to the chart." }, "velocity": { "type": [ "number", "null" ], "format": "float", "description": "Rank-velocity signal (positive = climbing)." }, "time_on_chart": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Length of time on the chart." }, "code2": { "type": [ "string", "null" ], "description": "Chart country code (ISO 3166-1 alpha-2 or `GLOBAL`)." }, "city_id": { "type": [ "integer", "null" ], "description": "Chartmetric city ID when the chart is city-scoped." }, "plays": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Total airplay plays for the artist in the chart window." }, "cm_artist": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Chartmetric artist ID." }, "id": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 2147483647 }, { "type": "string" } ], "nullable": true, "description": "Chartmetric artist ID (echoed from artist-info join)." }, "name": { "type": [ "string", "null" ], "description": "Artist name." }, "image_url": { "type": [ "string", "null" ], "description": "Artist image URL." }, "isni": { "type": [ "string", "null" ], "description": "International Standard Name Identifier (ISNI)." }, "hometown_city": { "type": [ "string", "null" ], "description": "Artist hometown city." }, "current_city": { "type": [ "string", "null" ], "description": "Artist current city." }, "sp_followers": { "type": [ "integer", "null" ], "description": "Spotify followers count." }, "sp_popularity": { "type": [ "integer", "null" ], "description": "Spotify popularity score (0–100)." }, "sp_monthly_listeners": { "type": [ "integer", "null" ], "description": "Spotify monthly listeners count." }, "deezer_fans": { "type": [ "integer", "null" ], "description": "Deezer fans count." }, "tags": { "type": [ "array", "null" ], "items": {}, "description": "Genre tags associated with the artist." }, "spotify_artist_ids": { "type": [ "array", "null" ], "items": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "nullable": true }, "description": "Spotify artist IDs." }, "itunes_artist_ids": { "type": [ "array", "null" ], "items": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "nullable": true }, "description": "iTunes artist IDs." }, "deezer_artist_ids": { "type": [ "array", "null" ], "items": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "nullable": true }, "description": "Deezer artist IDs." }, "amazon_artist_ids": { "type": [ "array", "null" ], "items": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "nullable": true }, "description": "Amazon artist IDs." }, "cm_artist_rank": { "type": [ "integer", "null" ], "description": "Chartmetric artist rank." }, "rankStats": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "rank": { "type": [ "integer", "null" ], "description": "Rank at `timestp` (1 = top)." }, "plays": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Play count at `timestp` (ACR airplay)." }, "timestp": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string" } ], "nullable": true, "description": "Timestamp of the sample." } } }, "description": "Historical rank + plays samples." } } }, "description": "Chart rows ordered by rank (1 = highest)." } } } }, "additionalProperties": false } } } } } } }, "/api/charts/twitch/users": { "get": { "summary": "Twitch User Charts", "tags": [ "Charts" ], "operationId": "getTwitchUserCharts", "description": "Twitch user charts by `duration` (daily/weekly/monthly) and `type` (followers or view counts). Handler builds the source `twitch_*_chart` table dynamically, then merges platform-linked artist info and historical `rankStats` from `QUERY_GET_USER_RANKINGS.TWITCH`.", "parameters": [ { "name": "date", "in": "query", "schema": { "type": "string", "format": "date-time", "description": "Charting date (`YYYY-MM-DD`); defaults to the latest available chart." }, "required": false, "description": "Charting date (`YYYY-MM-DD`); defaults to the latest available chart." }, { "name": "since", "in": "query", "schema": { "anyOf": [ { "type": "string", "format": "date-time", "x-required": true } ], "description": "Lower bound of the date range (YYYY-MM-DD). Required unless `latest=true`." }, "required": false, "description": "Lower bound of the date range (YYYY-MM-DD). Required unless `latest=true`." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "description": "Maximum entries returned (max 500)." }, "required": false, "description": "Maximum entries returned (max 500)." }, { "name": "duration", "in": "query", "schema": { "type": "string", "enum": [ "daily", "weekly", "monthly" ], "description": "Chart duration. `daily` requires `type=followers`; `monthly` requires `type=viewer_hours`." }, "required": true, "description": "Chart duration. `daily` requires `type=followers`; `monthly` requires `type=viewer_hours`.", "examples": { "default": { "value": "daily" } } }, { "name": "type", "in": "query", "schema": { "anyOf": [ { "type": "string", "enum": [ "followers" ], "not": { "enum": [ "viewer_hours" ] }, "x-required": true }, { "type": "string", "enum": [ "viewer_hours" ], "not": { "enum": [ "followers" ] }, "x-required": true }, { "type": "string", "enum": [ "followers", "viewer_hours" ], "x-required": true } ], "description": "Twitch chart type (`followers` or `viewer_hours`). Constrained by `duration` (see error messages)." }, "required": false, "description": "Twitch chart type (`followers` or `viewer_hours`). Constrained by `duration` (see error messages)." }, { "name": "latest", "in": "query", "schema": { "type": "boolean", "description": "If true, use the most recently available date and ignore `since`." }, "required": false, "description": "If true, use the most recently available date and ignore `since`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "object", "properties": { "length": { "type": [ "integer", "null" ], "description": "Number of chart rows in `data`." }, "data": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "rank": { "type": [ "integer", "null" ], "description": "Current chart rank (1 = top)." }, "pre_rank": { "type": [ "integer", "null" ], "description": "Position on the previous chart period." }, "peak_rank": { "type": [ "integer", "null" ], "description": "Best (lowest-numbered) rank reached." }, "peak_date": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string" } ], "nullable": true, "description": "Date `peak_rank` was achieved." }, "added_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string" } ], "nullable": true, "description": "Timestamp the user was added to the chart." }, "velocity": { "type": [ "number", "null" ], "format": "float", "description": "Rank-velocity signal (positive = climbing)." }, "time_on_chart": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Length of time on the chart." }, "twitch_user": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 2147483647 }, { "type": "string" } ], "nullable": true, "description": "Twitch user handle/ID." }, "followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Twitch followers count." }, "weekly_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Followers gained in the last 7 days." }, "monthly_followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Followers gained in the last 30 days." }, "count": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Daily viewer-hours count." }, "weekly_count": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Weekly viewer-hours count." }, "monthly_count": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Monthly viewer-hours count." }, "name": { "type": [ "string", "null" ], "description": "Twitch user / artist name." }, "image_url": { "type": [ "string", "null" ], "description": "Profile image URL." }, "link": { "type": [ "string", "null" ], "description": "Twitch profile link." }, "cm_artist": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Chartmetric artist ID linked to the Twitch user." }, "rankStats": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "rank": { "type": [ "integer", "null" ], "description": "Rank at `timestp` (1 = top)." }, "followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Followers count at `timestp` (Twitch)." }, "timestp": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string" } ], "nullable": true, "description": "Timestamp of the sample." } } }, "description": "Historical rank + followers samples." } } }, "description": "Chart rows ordered by rank (1 = highest)." } } } }, "additionalProperties": false } } } } } } }, "/api/charts/melon/track/{chartType}": { "get": { "summary": "Melon Track Chart", "tags": [ "Charts" ], "operationId": "getMelonTrackCharts", "description": "Return Melon track chart entries (historical positions, streaming trend, hydrated artist/album metadata). Served by the CCC (`cm_chart_cache_v2`) pipeline via `Charts.getChartsFromCH`. `chartType` accepts `general`, `k-pop`, `pop`, `others`, `top`, `hot`. `top` and `hot` are single charts with no `genre` / `duration` filters.", "parameters": [ { "name": "chartType", "in": "path", "schema": { "type": "string", "enum": [ "general", "pop", "k-pop", "others", "top", "hot" ], "description": "Melon track chart type (e.g. `general`, `k-pop`, `pop`, `others`, `top`, `hot`). `top`/`hot` are single charts and ignore `genre`/`duration`." }, "required": true, "description": "Melon track chart type (e.g. `general`, `k-pop`, `pop`, `others`, `top`, `hot`). `top`/`hot` are single charts and ignore `genre`/`duration`.", "examples": { "default": { "value": "general" } } }, { "name": "date", "in": "query", "schema": { "type": "string", "format": "date", "description": "Date for the chart slice (`YYYY-MM-DD`). Required unless `latest=true`." }, "required": false, "description": "Date for the chart slice (`YYYY-MM-DD`). Required unless `latest=true`." }, { "name": "latest", "in": "query", "schema": { "type": "boolean", "description": "If true, use the most recently available chart date and ignore `date`.", "default": false }, "required": false, "description": "If true, use the most recently available chart date and ignore `date`." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "description": "Maximum number of items to return per request.", "default": 100 }, "required": false, "description": "Maximum number of items to return per request." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, "required": false, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, { "name": "code2", "in": "query", "schema": { "anyOf": [ { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB')." }, { "type": "string", "enum": [ "GLOBAL" ] } ], "description": "ISO 3166-1 alpha-2 country code (uppercase, e.g. 'US') or 'GLOBAL'. When omitted, the platform's default chart scope applies." }, "required": false, "description": "ISO 3166-1 alpha-2 country code (uppercase, e.g. 'US') or 'GLOBAL'. When omitted, the platform's default chart scope applies." }, { "name": "duration", "in": "query", "schema": { "type": "string", "enum": [ "daily", "monthly", "weekly", "yearly", "semi-yearly", "real-time", "all_time" ], "description": "Chart duration window. One of `daily`, `monthly`, `weekly`, `yearly`, `semi-yearly`, `real-time`, `all_time`." }, "required": true, "description": "Chart duration window. One of `daily`, `monthly`, `weekly`, `yearly`, `semi-yearly`, `real-time`, `all_time`.", "examples": { "default": { "value": "daily" } } }, { "name": "genre", "in": "query", "schema": { "type": "string", "maxLength": 100, "description": "Genre filter for the chart slice. Lowercased and trimmed." }, "required": true, "description": "Genre filter for the chart slice. Lowercased and trimmed.", "examples": { "default": { "value": "example" } } }, { "name": "cityId", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric city ID to scope the chart to a city." }, "required": false, "description": "Chartmetric city ID to scope the chart to a city." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "entityId": { "type": [ "integer", "null" ], "description": "Internal Chartmetric entity ID." }, "targetId": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Platform-side track / album / user ID." }, "duration": { "type": [ "string", "null" ], "description": "Chart duration window (e.g. `daily`, `weekly`, `monthly`)." }, "country": { "type": [ "string", "null" ], "description": "Chart country code (ISO 3166-1 alpha-2; empty string for non-country-scoped charts)." }, "cityId": { "type": [ "integer", "null" ], "description": "Chartmetric city ID, or 0 when not city-scoped." }, "genre": { "type": [ "string", "null" ], "description": "Chart genre." }, "rank": { "type": [ "integer", "null" ], "description": "Current chart rank (1 = top)." }, "rankDiff": { "type": [ "number", "null" ], "format": "float", "description": "Rank change from the previous period (negative = climbed)." }, "rankTrend": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "timestp": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp at which the rank was recorded." }, "rank": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Rank at `timestp` (1 = top). Currently emitted as a string by the CCC pipeline." } } }, "description": "Historical rank samples for the row." }, "peakDate": { "type": [ "string", "null" ], "format": "date-time", "description": "Date the entity achieved its peak rank." }, "peakRank": { "type": [ "integer", "null" ], "description": "Best (lowest-numbered) rank achieved." }, "velocity7Day": { "type": [ "number", "null" ], "format": "float", "description": "7-day rank velocity (positive = trending up)." }, "periodsOnChart": { "type": [ "integer", "null" ], "description": "Total chart periods on the chart." }, "consecutivePeriods": { "type": [ "integer", "null" ], "description": "Consecutive chart periods without falling off." }, "chartedDate": { "type": [ "string", "null" ], "format": "date-time", "description": "Date of the chart row." }, "name": { "type": [ "string", "null" ], "description": "Entity name (track / album)." }, "imageUrl": { "type": [ "string", "null" ], "description": "Entity cover image URL." }, "createdAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Cache row creation timestamp." }, "artists": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ], "description": "Chartmetric artist ID." }, "name": { "type": [ "string", "null" ], "description": "Artist name." }, "code2": { "type": [ "string", "null" ], "description": "Artist country code (ISO 3166-1 alpha-2)." }, "careerStage": { "type": [ "string", "null" ], "description": "Artist career stage (e.g. `undiscovered`, `developing`, `mid-level`, `mainstream`, `superstar`, `legendary`)." }, "imageUrl": { "type": [ "string", "null" ], "description": "Artist image URL." } } }, "description": "Artists associated with the entity." }, "album": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "integer", "null" ], "description": "Chartmetric album ID." }, "name": { "type": [ "string", "null" ], "description": "Album name." }, "label": { "type": [ "string", "null" ], "description": "Album record label." }, "releaseDate": { "type": [ "string", "null" ], "format": "date-time", "description": "Album release date." } }, "description": "Album the entity belongs to (or the album itself for album charts)." }, "optionalRows": { "type": "object", "properties": { "overallRank": { "type": [ "number", "null" ], "format": "float", "description": "Overall ranking across the platform (legacy field)." }, "videos": { "type": [ "number", "null" ], "format": "float", "description": "Number of videos contributing to the row." }, "totalVideos": { "type": [ "number", "null" ], "format": "float", "description": "Total videos across the entity." }, "metricValue": { "type": [ "number", "null" ], "format": "float", "description": "Primary metric value driving the chart position." }, "metricDiff": { "type": [ "number", "null" ], "format": "float", "description": "Change in `metricValue` vs the previous period." }, "avgPosition": { "type": [ "number", "null" ], "format": "float", "description": "Average position over the chart window." }, "score": { "type": [ "number", "null" ], "format": "float", "description": "Score driving the chart position." }, "totalFollowers": { "type": [ "number", "null" ], "format": "float", "description": "Total followers across the entity." }, "velocity": { "type": [ "number", "null" ], "format": "float", "description": "Rank-velocity signal (positive = climbing)." }, "isComeback": { "type": [ "boolean", "null" ], "description": "True when the entity re-entered the chart after a break (comeback)." }, "plays": { "type": [ "number", "null" ], "format": "float", "description": "Play count contribution." }, "playsWeekly": { "type": [ "number", "null" ], "format": "float", "description": "Weekly play count." }, "counts": { "type": [ "number", "null" ], "format": "float", "description": "Generic count metric." }, "index": { "type": [ "number", "null" ], "format": "float", "description": "Generic chart index value." }, "comments": { "type": [ "number", "null" ], "format": "float", "description": "Comment count." }, "artistName": { "type": [ "string", "null" ], "description": "Primary artist name (legacy field)." }, "label": { "type": [ "string", "null" ], "description": "Album label (Hanteo physical-record charts)." }, "physicalRecordIndex": { "type": [ "string", "null" ], "description": "Hanteo physical-record index value." }, "albumName": { "type": [ "string", "null" ], "description": "Album name (legacy field)." }, "name": { "type": [ "string", "null" ], "description": "Entity name passthrough." }, "imageUrl": { "type": [ "string", "null" ], "description": "Image URL passthrough." }, "id": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Platform identifier (legacy passthrough)." }, "platformId": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Platform-specific external identifier." } }, "description": "Per-chart optional metrics (legacy name; populated on Melon/Hanteo/Circle/Line Music/Pandora/Anghami)." }, "optionalFields": { "type": "object", "properties": { "overallRank": { "type": [ "number", "null" ], "format": "float", "description": "Overall ranking across the platform (legacy field)." }, "videos": { "type": [ "number", "null" ], "format": "float", "description": "Number of videos contributing to the row." }, "totalVideos": { "type": [ "number", "null" ], "format": "float", "description": "Total videos across the entity." }, "metricValue": { "type": [ "number", "null" ], "format": "float", "description": "Primary metric value driving the chart position." }, "metricDiff": { "type": [ "number", "null" ], "format": "float", "description": "Change in `metricValue` vs the previous period." }, "avgPosition": { "type": [ "number", "null" ], "format": "float", "description": "Average position over the chart window." }, "score": { "type": [ "number", "null" ], "format": "float", "description": "Score driving the chart position." }, "totalFollowers": { "type": [ "number", "null" ], "format": "float", "description": "Total followers across the entity." }, "velocity": { "type": [ "number", "null" ], "format": "float", "description": "Rank-velocity signal (positive = climbing)." }, "isComeback": { "type": [ "boolean", "null" ], "description": "True when the entity re-entered the chart after a break (comeback)." }, "plays": { "type": [ "number", "null" ], "format": "float", "description": "Play count contribution." }, "playsWeekly": { "type": [ "number", "null" ], "format": "float", "description": "Weekly play count." }, "counts": { "type": [ "number", "null" ], "format": "float", "description": "Generic count metric." }, "index": { "type": [ "number", "null" ], "format": "float", "description": "Generic chart index value." }, "comments": { "type": [ "number", "null" ], "format": "float", "description": "Comment count." }, "artistName": { "type": [ "string", "null" ], "description": "Primary artist name (legacy field)." }, "label": { "type": [ "string", "null" ], "description": "Album label (Hanteo physical-record charts)." }, "physicalRecordIndex": { "type": [ "string", "null" ], "description": "Hanteo physical-record index value." }, "albumName": { "type": [ "string", "null" ], "description": "Album name (legacy field)." }, "name": { "type": [ "string", "null" ], "description": "Entity name passthrough." }, "imageUrl": { "type": [ "string", "null" ], "description": "Image URL passthrough." }, "id": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Platform identifier (legacy passthrough)." }, "platformId": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Platform-specific external identifier." } }, "description": "Per-chart optional metrics (used by the new SoundCloud chart and the hydrated TS row type)." }, "targetExtras": { "type": "object", "properties": { "airplayStreams": { "type": [ "number", "null" ], "format": "float", "description": "Airplay stream count snapshot." }, "amazonEdPlaylistCount": { "type": [ "number", "null" ], "format": "float", "description": "Number of Amazon editorial playlists containing the track." }, "amazonPlaylistCount": { "type": [ "number", "null" ], "format": "float", "description": "Number of Amazon playlists containing the track." }, "anghamiLikes": { "type": [ "number", "null" ], "format": "float", "description": "Anghami like count." }, "anghamiPlays": { "type": [ "number", "null" ], "format": "float", "description": "Anghami play count." }, "deezerEdPlaylistCount": { "type": [ "number", "null" ], "format": "float", "description": "Number of Deezer editorial playlists containing the track." }, "deezerEdPlaylistTotalReach": { "type": [ "number", "null" ], "format": "float", "description": "Total follower reach across Deezer editorial playlists." }, "deezerPlaylistCount": { "type": [ "number", "null" ], "format": "float", "description": "Number of Deezer playlists containing the track." }, "deezerPlaylistTotalReach": { "type": [ "number", "null" ], "format": "float", "description": "Total follower reach across Deezer playlists." }, "itunesEdPlaylistCount": { "type": [ "number", "null" ], "format": "float", "description": "Number of iTunes editorial playlists containing the track." }, "itunesPlaylistCount": { "type": [ "number", "null" ], "format": "float", "description": "Number of iTunes playlists containing the track." }, "lineMusicLikes": { "type": [ "number", "null" ], "format": "float", "description": "Line Music like count." }, "lineMusicListenCount": { "type": [ "number", "null" ], "format": "float", "description": "Line Music listen count." }, "melonComments": { "type": [ "number", "null" ], "format": "float", "description": "Melon comment count." }, "melonLikes": { "type": [ "number", "null" ], "format": "float", "description": "Melon like count." }, "pandoraLifetimeStationsAdded": { "type": [ "number", "null" ], "format": "float", "description": "Pandora lifetime station-additions count." }, "pandoraLifetimeStreams": { "type": [ "number", "null" ], "format": "float", "description": "Pandora lifetime stream count." }, "shazamCount": { "type": [ "number", "null" ], "format": "float", "description": "Shazam tag count." }, "siriusxmStreams": { "type": [ "number", "null" ], "format": "float", "description": "SiriusXM stream count." }, "soundcloudPlays": { "type": [ "number", "null" ], "format": "float", "description": "SoundCloud play count." }, "spotifyEdPlaylistCount": { "type": [ "number", "null" ], "format": "float", "description": "Number of Spotify editorial playlists containing the track." }, "spotifyEdPlaylistTotalReach": { "type": [ "number", "null" ], "format": "float", "description": "Total follower reach across Spotify editorial playlists." }, "spotifyPlaylistCount": { "type": [ "number", "null" ], "format": "float", "description": "Number of Spotify playlists containing the track." }, "spotifyPlaylistTotalReach": { "type": [ "number", "null" ], "format": "float", "description": "Total follower reach across Spotify playlists." }, "spotifyPlays": { "type": [ "number", "null" ], "format": "float", "description": "Spotify play count snapshot." }, "spotifyPopularity": { "type": [ "number", "null" ], "format": "float", "description": "Spotify popularity score (0–100)." }, "tiktokTopVideosComments": { "type": [ "number", "null" ], "format": "float", "description": "Comment count across the track's top TikTok videos." }, "tiktokTopVideosLikes": { "type": [ "number", "null" ], "format": "float", "description": "Like count across the track's top TikTok videos." }, "tiktokTopVideosViews": { "type": [ "number", "null" ], "format": "float", "description": "View count across the track's top TikTok videos." }, "youtubeComments": { "type": [ "number", "null" ], "format": "float", "description": "YouTube comment count." }, "youtubeEdPlaylistCount": { "type": [ "number", "null" ], "format": "float", "description": "Number of YouTube editorial playlists containing the track." }, "youtubeEdPlaylistTotalReach": { "type": [ "number", "null" ], "format": "float", "description": "Total follower reach across YouTube editorial playlists." }, "youtubeLikes": { "type": [ "number", "null" ], "format": "float", "description": "YouTube like count." }, "youtubePlaylistCount": { "type": [ "number", "null" ], "format": "float", "description": "Number of YouTube playlists containing the track." }, "youtubePlaylistTotalReach": { "type": [ "number", "null" ], "format": "float", "description": "Total follower reach across YouTube playlists." }, "youtubeViews": { "type": [ "number", "null" ], "format": "float", "description": "YouTube view count." } }, "description": "Cross-platform metric snapshots hydrated from per-target cache rows." }, "isChartGenre": { "type": [ "boolean", "null" ], "description": "True when the entity's genre matches the chart's genre filter." }, "externalId": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Platform external identifier (e.g. Hanteo internal index, SoundCloud track ID)." }, "externalUrl": { "type": [ "string", "null" ], "description": "Platform external URL." }, "isrc": { "type": [ "string", "null" ], "description": "International Standard Recording Code (SoundCloud chart only)." }, "entityGenre": { "type": [ "string", "null" ], "description": "Entity-level genre (when distinct from chart genre)." }, "id": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Numeric platform ID (Hanteo legacy field)." }, "platform_id": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Platform-side external ID (Hanteo legacy field)." } } }, "description": "List of regional chart rows." } }, "additionalProperties": false }, "examples": { "default": { "value": { "obj": [ { "entityId": 144447279, "targetId": "38626852", "duration": "daily", "country": "", "cityId": 0, "genre": "All Genres", "rank": 1, "rankDiff": 0, "rankTrend": [ { "timestp": "2025-05-28", "rank": "1" }, { "timestp": "2025-05-29", "rank": "1" } ], "peakDate": "2025-05-11", "peakRank": 1, "velocity7Day": 0, "periodsOnChart": 85, "consecutivePeriods": 85, "chartedDate": "2025-05-30", "name": "To Reach You (Inst.)", "imageUrl": "https://i.scdn.co/image/ab67616d0000b27358c6956da5fa380b67986551", "createdAt": "2025-06-03T07:24:14.000Z", "artists": [ { "careerStage": "mainstream", "code2": "KR", "id": 217578, "name": "10CM", "imageUrl": "https://i.scdn.co/image/ab6761610000e5eb2445af13cb1a8132388cd566" } ], "album": { "id": 42895219, "name": "To Reach You", "label": "CAM", "releaseDate": "2025-03-06T00:00:00.000Z" }, "optionalRows": { "overallRank": 0, "metricValue": 0, "metricDiff": null, "score": 0, "isComeback": false, "plays": 0 }, "targetExtras": { "melonComments": 698, "melonLikes": 114826, "spotifyPopularity": 30 }, "isChartGenre": true } ] } } } } } } } } }, "/api/charts/hanteo/{entityType}/{chartType}": { "get": { "summary": "Hanteo Chart", "tags": [ "Charts" ], "operationId": "getHanteoCharts", "description": "Return Hanteo chart entries for the given `entityType` (`track` or `album`). Shape matches the generic regional CCC chart row; hydrated rows may also expose `externalId`, `id`, `platform_id`, and a `physicalRecordIndex` inside `optionalRows`.", "parameters": [ { "name": "entityType", "in": "path", "schema": { "type": "string", "enum": [ "track", "album", "artist", "video" ], "description": "Chart entity (`track` or `album`)." }, "required": true, "description": "Chart entity (`track` or `album`).", "examples": { "default": { "value": "track" } } }, { "name": "chartType", "in": "path", "schema": { "type": "string", "enum": [ "digital", "top", "music", "world" ], "description": "Hanteo chart type. Allowed values depend on `entityType`." }, "required": true, "description": "Hanteo chart type. Allowed values depend on `entityType`.", "examples": { "default": { "value": "digital" } } }, { "name": "date", "in": "query", "schema": { "type": "string", "format": "date", "description": "Date for the chart slice (`YYYY-MM-DD`). Required unless `latest=true`." }, "required": false, "description": "Date for the chart slice (`YYYY-MM-DD`). Required unless `latest=true`." }, { "name": "latest", "in": "query", "schema": { "type": "boolean", "description": "If true, use the most recently available chart date and ignore `date`.", "default": false }, "required": false, "description": "If true, use the most recently available chart date and ignore `date`." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "description": "Maximum number of items to return per request.", "default": 100 }, "required": false, "description": "Maximum number of items to return per request." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, "required": false, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, { "name": "code2", "in": "query", "schema": { "anyOf": [ { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB')." }, { "type": "string", "enum": [ "GLOBAL" ] } ], "description": "ISO 3166-1 alpha-2 country code (uppercase, e.g. 'US') or 'GLOBAL'. When omitted, the platform's default chart scope applies." }, "required": false, "description": "ISO 3166-1 alpha-2 country code (uppercase, e.g. 'US') or 'GLOBAL'. When omitted, the platform's default chart scope applies." }, { "name": "duration", "in": "query", "schema": { "type": "string", "enum": [ "daily", "monthly", "weekly", "yearly", "semi-yearly", "real-time", "all_time" ], "description": "Chart duration window. One of `daily`, `monthly`, `weekly`, `yearly`, `semi-yearly`, `real-time`, `all_time`." }, "required": true, "description": "Chart duration window. One of `daily`, `monthly`, `weekly`, `yearly`, `semi-yearly`, `real-time`, `all_time`.", "examples": { "default": { "value": "daily" } } }, { "name": "genre", "in": "query", "schema": { "type": "string", "maxLength": 100, "description": "Genre filter for the chart slice. Lowercased and trimmed." }, "required": false, "description": "Genre filter for the chart slice. Lowercased and trimmed." }, { "name": "cityId", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric city ID to scope the chart to a city." }, "required": false, "description": "Chartmetric city ID to scope the chart to a city." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "entityId": { "type": [ "integer", "null" ], "description": "Internal Chartmetric entity ID." }, "targetId": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Platform-side track / album / user ID." }, "duration": { "type": [ "string", "null" ], "description": "Chart duration window (e.g. `daily`, `weekly`, `monthly`)." }, "country": { "type": [ "string", "null" ], "description": "Chart country code (ISO 3166-1 alpha-2; empty string for non-country-scoped charts)." }, "cityId": { "type": [ "integer", "null" ], "description": "Chartmetric city ID, or 0 when not city-scoped." }, "genre": { "type": [ "string", "null" ], "description": "Chart genre." }, "rank": { "type": [ "integer", "null" ], "description": "Current chart rank (1 = top)." }, "rankDiff": { "type": [ "number", "null" ], "format": "float", "description": "Rank change from the previous period (negative = climbed)." }, "rankTrend": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "timestp": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp at which the rank was recorded." }, "rank": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Rank at `timestp` (1 = top). Currently emitted as a string by the CCC pipeline." } } }, "description": "Historical rank samples for the row." }, "peakDate": { "type": [ "string", "null" ], "format": "date-time", "description": "Date the entity achieved its peak rank." }, "peakRank": { "type": [ "integer", "null" ], "description": "Best (lowest-numbered) rank achieved." }, "velocity7Day": { "type": [ "number", "null" ], "format": "float", "description": "7-day rank velocity (positive = trending up)." }, "periodsOnChart": { "type": [ "integer", "null" ], "description": "Total chart periods on the chart." }, "consecutivePeriods": { "type": [ "integer", "null" ], "description": "Consecutive chart periods without falling off." }, "chartedDate": { "type": [ "string", "null" ], "format": "date-time", "description": "Date of the chart row." }, "name": { "type": [ "string", "null" ], "description": "Entity name (track / album)." }, "imageUrl": { "type": [ "string", "null" ], "description": "Entity cover image URL." }, "createdAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Cache row creation timestamp." }, "artists": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ], "description": "Chartmetric artist ID." }, "name": { "type": [ "string", "null" ], "description": "Artist name." }, "code2": { "type": [ "string", "null" ], "description": "Artist country code (ISO 3166-1 alpha-2)." }, "careerStage": { "type": [ "string", "null" ], "description": "Artist career stage (e.g. `undiscovered`, `developing`, `mid-level`, `mainstream`, `superstar`, `legendary`)." }, "imageUrl": { "type": [ "string", "null" ], "description": "Artist image URL." } } }, "description": "Artists associated with the entity." }, "album": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "integer", "null" ], "description": "Chartmetric album ID." }, "name": { "type": [ "string", "null" ], "description": "Album name." }, "label": { "type": [ "string", "null" ], "description": "Album record label." }, "releaseDate": { "type": [ "string", "null" ], "format": "date-time", "description": "Album release date." } }, "description": "Album the entity belongs to (or the album itself for album charts)." }, "optionalRows": { "type": "object", "properties": { "overallRank": { "type": [ "number", "null" ], "format": "float", "description": "Overall ranking across the platform (legacy field)." }, "videos": { "type": [ "number", "null" ], "format": "float", "description": "Number of videos contributing to the row." }, "totalVideos": { "type": [ "number", "null" ], "format": "float", "description": "Total videos across the entity." }, "metricValue": { "type": [ "number", "null" ], "format": "float", "description": "Primary metric value driving the chart position." }, "metricDiff": { "type": [ "number", "null" ], "format": "float", "description": "Change in `metricValue` vs the previous period." }, "avgPosition": { "type": [ "number", "null" ], "format": "float", "description": "Average position over the chart window." }, "score": { "type": [ "number", "null" ], "format": "float", "description": "Score driving the chart position." }, "totalFollowers": { "type": [ "number", "null" ], "format": "float", "description": "Total followers across the entity." }, "velocity": { "type": [ "number", "null" ], "format": "float", "description": "Rank-velocity signal (positive = climbing)." }, "isComeback": { "type": [ "boolean", "null" ], "description": "True when the entity re-entered the chart after a break (comeback)." }, "plays": { "type": [ "number", "null" ], "format": "float", "description": "Play count contribution." }, "playsWeekly": { "type": [ "number", "null" ], "format": "float", "description": "Weekly play count." }, "counts": { "type": [ "number", "null" ], "format": "float", "description": "Generic count metric." }, "index": { "type": [ "number", "null" ], "format": "float", "description": "Generic chart index value." }, "comments": { "type": [ "number", "null" ], "format": "float", "description": "Comment count." }, "artistName": { "type": [ "string", "null" ], "description": "Primary artist name (legacy field)." }, "label": { "type": [ "string", "null" ], "description": "Album label (Hanteo physical-record charts)." }, "physicalRecordIndex": { "type": [ "string", "null" ], "description": "Hanteo physical-record index value." }, "albumName": { "type": [ "string", "null" ], "description": "Album name (legacy field)." }, "name": { "type": [ "string", "null" ], "description": "Entity name passthrough." }, "imageUrl": { "type": [ "string", "null" ], "description": "Image URL passthrough." }, "id": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Platform identifier (legacy passthrough)." }, "platformId": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Platform-specific external identifier." } }, "description": "Per-chart optional metrics (legacy name; populated on Melon/Hanteo/Circle/Line Music/Pandora/Anghami)." }, "optionalFields": { "type": "object", "properties": { "overallRank": { "type": [ "number", "null" ], "format": "float", "description": "Overall ranking across the platform (legacy field)." }, "videos": { "type": [ "number", "null" ], "format": "float", "description": "Number of videos contributing to the row." }, "totalVideos": { "type": [ "number", "null" ], "format": "float", "description": "Total videos across the entity." }, "metricValue": { "type": [ "number", "null" ], "format": "float", "description": "Primary metric value driving the chart position." }, "metricDiff": { "type": [ "number", "null" ], "format": "float", "description": "Change in `metricValue` vs the previous period." }, "avgPosition": { "type": [ "number", "null" ], "format": "float", "description": "Average position over the chart window." }, "score": { "type": [ "number", "null" ], "format": "float", "description": "Score driving the chart position." }, "totalFollowers": { "type": [ "number", "null" ], "format": "float", "description": "Total followers across the entity." }, "velocity": { "type": [ "number", "null" ], "format": "float", "description": "Rank-velocity signal (positive = climbing)." }, "isComeback": { "type": [ "boolean", "null" ], "description": "True when the entity re-entered the chart after a break (comeback)." }, "plays": { "type": [ "number", "null" ], "format": "float", "description": "Play count contribution." }, "playsWeekly": { "type": [ "number", "null" ], "format": "float", "description": "Weekly play count." }, "counts": { "type": [ "number", "null" ], "format": "float", "description": "Generic count metric." }, "index": { "type": [ "number", "null" ], "format": "float", "description": "Generic chart index value." }, "comments": { "type": [ "number", "null" ], "format": "float", "description": "Comment count." }, "artistName": { "type": [ "string", "null" ], "description": "Primary artist name (legacy field)." }, "label": { "type": [ "string", "null" ], "description": "Album label (Hanteo physical-record charts)." }, "physicalRecordIndex": { "type": [ "string", "null" ], "description": "Hanteo physical-record index value." }, "albumName": { "type": [ "string", "null" ], "description": "Album name (legacy field)." }, "name": { "type": [ "string", "null" ], "description": "Entity name passthrough." }, "imageUrl": { "type": [ "string", "null" ], "description": "Image URL passthrough." }, "id": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Platform identifier (legacy passthrough)." }, "platformId": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Platform-specific external identifier." } }, "description": "Per-chart optional metrics (used by the new SoundCloud chart and the hydrated TS row type)." }, "targetExtras": { "type": "object", "properties": { "airplayStreams": { "type": [ "number", "null" ], "format": "float", "description": "Airplay stream count snapshot." }, "amazonEdPlaylistCount": { "type": [ "number", "null" ], "format": "float", "description": "Number of Amazon editorial playlists containing the track." }, "amazonPlaylistCount": { "type": [ "number", "null" ], "format": "float", "description": "Number of Amazon playlists containing the track." }, "anghamiLikes": { "type": [ "number", "null" ], "format": "float", "description": "Anghami like count." }, "anghamiPlays": { "type": [ "number", "null" ], "format": "float", "description": "Anghami play count." }, "deezerEdPlaylistCount": { "type": [ "number", "null" ], "format": "float", "description": "Number of Deezer editorial playlists containing the track." }, "deezerEdPlaylistTotalReach": { "type": [ "number", "null" ], "format": "float", "description": "Total follower reach across Deezer editorial playlists." }, "deezerPlaylistCount": { "type": [ "number", "null" ], "format": "float", "description": "Number of Deezer playlists containing the track." }, "deezerPlaylistTotalReach": { "type": [ "number", "null" ], "format": "float", "description": "Total follower reach across Deezer playlists." }, "itunesEdPlaylistCount": { "type": [ "number", "null" ], "format": "float", "description": "Number of iTunes editorial playlists containing the track." }, "itunesPlaylistCount": { "type": [ "number", "null" ], "format": "float", "description": "Number of iTunes playlists containing the track." }, "lineMusicLikes": { "type": [ "number", "null" ], "format": "float", "description": "Line Music like count." }, "lineMusicListenCount": { "type": [ "number", "null" ], "format": "float", "description": "Line Music listen count." }, "melonComments": { "type": [ "number", "null" ], "format": "float", "description": "Melon comment count." }, "melonLikes": { "type": [ "number", "null" ], "format": "float", "description": "Melon like count." }, "pandoraLifetimeStationsAdded": { "type": [ "number", "null" ], "format": "float", "description": "Pandora lifetime station-additions count." }, "pandoraLifetimeStreams": { "type": [ "number", "null" ], "format": "float", "description": "Pandora lifetime stream count." }, "shazamCount": { "type": [ "number", "null" ], "format": "float", "description": "Shazam tag count." }, "siriusxmStreams": { "type": [ "number", "null" ], "format": "float", "description": "SiriusXM stream count." }, "soundcloudPlays": { "type": [ "number", "null" ], "format": "float", "description": "SoundCloud play count." }, "spotifyEdPlaylistCount": { "type": [ "number", "null" ], "format": "float", "description": "Number of Spotify editorial playlists containing the track." }, "spotifyEdPlaylistTotalReach": { "type": [ "number", "null" ], "format": "float", "description": "Total follower reach across Spotify editorial playlists." }, "spotifyPlaylistCount": { "type": [ "number", "null" ], "format": "float", "description": "Number of Spotify playlists containing the track." }, "spotifyPlaylistTotalReach": { "type": [ "number", "null" ], "format": "float", "description": "Total follower reach across Spotify playlists." }, "spotifyPlays": { "type": [ "number", "null" ], "format": "float", "description": "Spotify play count snapshot." }, "spotifyPopularity": { "type": [ "number", "null" ], "format": "float", "description": "Spotify popularity score (0–100)." }, "tiktokTopVideosComments": { "type": [ "number", "null" ], "format": "float", "description": "Comment count across the track's top TikTok videos." }, "tiktokTopVideosLikes": { "type": [ "number", "null" ], "format": "float", "description": "Like count across the track's top TikTok videos." }, "tiktokTopVideosViews": { "type": [ "number", "null" ], "format": "float", "description": "View count across the track's top TikTok videos." }, "youtubeComments": { "type": [ "number", "null" ], "format": "float", "description": "YouTube comment count." }, "youtubeEdPlaylistCount": { "type": [ "number", "null" ], "format": "float", "description": "Number of YouTube editorial playlists containing the track." }, "youtubeEdPlaylistTotalReach": { "type": [ "number", "null" ], "format": "float", "description": "Total follower reach across YouTube editorial playlists." }, "youtubeLikes": { "type": [ "number", "null" ], "format": "float", "description": "YouTube like count." }, "youtubePlaylistCount": { "type": [ "number", "null" ], "format": "float", "description": "Number of YouTube playlists containing the track." }, "youtubePlaylistTotalReach": { "type": [ "number", "null" ], "format": "float", "description": "Total follower reach across YouTube playlists." }, "youtubeViews": { "type": [ "number", "null" ], "format": "float", "description": "YouTube view count." } }, "description": "Cross-platform metric snapshots hydrated from per-target cache rows." }, "isChartGenre": { "type": [ "boolean", "null" ], "description": "True when the entity's genre matches the chart's genre filter." }, "externalId": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Platform external identifier (e.g. Hanteo internal index, SoundCloud track ID)." }, "externalUrl": { "type": [ "string", "null" ], "description": "Platform external URL." }, "isrc": { "type": [ "string", "null" ], "description": "International Standard Recording Code (SoundCloud chart only)." }, "entityGenre": { "type": [ "string", "null" ], "description": "Entity-level genre (when distinct from chart genre)." }, "id": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Numeric platform ID (Hanteo legacy field)." }, "platform_id": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Platform-side external ID (Hanteo legacy field)." } } }, "description": "List of regional chart rows." } }, "additionalProperties": false }, "examples": { "default": { "value": { "obj": [ { "entityId": 144447279, "targetId": "78", "duration": "daily", "country": "", "cityId": 0, "genre": "rock, pop, k-pop", "rank": 1, "rankDiff": 0, "rankTrend": [ { "timestp": "2025-05-31", "rank": "1" } ], "peakDate": "2025-05-11", "peakRank": 1, "velocity7Day": 0, "periodsOnChart": 46, "consecutivePeriods": 46, "chartedDate": "2025-06-03", "name": "Song title", "imageUrl": "https://i.scdn.co/image/ab67616d0000b27358c6956da5fa380b67986551", "createdAt": "2025-06-09T02:20:15.000Z", "artists": [ { "careerStage": "mainstream", "code2": "KR", "id": 217578, "name": "10CM", "imageUrl": "https://i.scdn.co/image/ab6761610000e5eb2445af13cb1a8132388cd566" } ], "album": { "id": 42895219, "name": "Album title", "label": "CAM", "releaseDate": "2025-03-06T00:00:00.000Z" }, "externalId": 1830886, "optionalRows": { "physicalRecordIndex": "9963.93", "label": "CAM", "overallRank": 0, "score": 0, "isComeback": false }, "targetExtras": { "spotifyPopularity": 30 }, "isChartGenre": false, "id": 78, "platform_id": 1830886 } ] } } } } } } } } }, "/api/charts/circle/{entityType}/{chartType}": { "get": { "summary": "Circle Chart", "tags": [ "Charts" ], "operationId": "getCircleCharts", "description": "Return Circle (Gaon) chart entries for the given `entityType` (`track` or `album`). Shape matches the generic regional CCC chart row. Hydrated rows may include `externalId`.", "parameters": [ { "name": "entityType", "in": "path", "schema": { "type": "string", "enum": [ "track", "album", "artist", "video" ], "description": "Chart entity (`track` or `album`)." }, "required": true, "description": "Chart entity (`track` or `album`).", "examples": { "default": { "value": "track" } } }, { "name": "chartType", "in": "path", "schema": { "type": "string", "enum": [ "global_k_pop", "digital", "top", "retail" ], "description": "Circle (Gaon) chart type. Allowed values depend on `entityType`." }, "required": true, "description": "Circle (Gaon) chart type. Allowed values depend on `entityType`.", "examples": { "default": { "value": "global_k_pop" } } }, { "name": "date", "in": "query", "schema": { "type": "string", "format": "date", "description": "Date for the chart slice (`YYYY-MM-DD`). Required unless `latest=true`." }, "required": false, "description": "Date for the chart slice (`YYYY-MM-DD`). Required unless `latest=true`." }, { "name": "latest", "in": "query", "schema": { "type": "boolean", "description": "If true, use the most recently available chart date and ignore `date`.", "default": false }, "required": false, "description": "If true, use the most recently available chart date and ignore `date`." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "description": "Maximum number of items to return per request.", "default": 100 }, "required": false, "description": "Maximum number of items to return per request." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, "required": false, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, { "name": "code2", "in": "query", "schema": { "anyOf": [ { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB')." }, { "type": "string", "enum": [ "GLOBAL" ] } ], "description": "ISO 3166-1 alpha-2 country code (uppercase, e.g. 'US') or 'GLOBAL'. When omitted, the platform's default chart scope applies." }, "required": false, "description": "ISO 3166-1 alpha-2 country code (uppercase, e.g. 'US') or 'GLOBAL'. When omitted, the platform's default chart scope applies." }, { "name": "duration", "in": "query", "schema": { "type": "string", "enum": [ "daily", "monthly", "weekly", "yearly", "semi-yearly", "real-time", "all_time" ], "description": "Chart duration window. One of `daily`, `monthly`, `weekly`, `yearly`, `semi-yearly`, `real-time`, `all_time`." }, "required": true, "description": "Chart duration window. One of `daily`, `monthly`, `weekly`, `yearly`, `semi-yearly`, `real-time`, `all_time`.", "examples": { "default": { "value": "daily" } } }, { "name": "genre", "in": "query", "schema": { "type": "string", "maxLength": 100, "description": "Genre filter for the chart slice. Lowercased and trimmed." }, "required": false, "description": "Genre filter for the chart slice. Lowercased and trimmed." }, { "name": "cityId", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric city ID to scope the chart to a city." }, "required": false, "description": "Chartmetric city ID to scope the chart to a city." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "entityId": { "type": [ "integer", "null" ], "description": "Internal Chartmetric entity ID." }, "targetId": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Platform-side track / album / user ID." }, "duration": { "type": [ "string", "null" ], "description": "Chart duration window (e.g. `daily`, `weekly`, `monthly`)." }, "country": { "type": [ "string", "null" ], "description": "Chart country code (ISO 3166-1 alpha-2; empty string for non-country-scoped charts)." }, "cityId": { "type": [ "integer", "null" ], "description": "Chartmetric city ID, or 0 when not city-scoped." }, "genre": { "type": [ "string", "null" ], "description": "Chart genre." }, "rank": { "type": [ "integer", "null" ], "description": "Current chart rank (1 = top)." }, "rankDiff": { "type": [ "number", "null" ], "format": "float", "description": "Rank change from the previous period (negative = climbed)." }, "rankTrend": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "timestp": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp at which the rank was recorded." }, "rank": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Rank at `timestp` (1 = top). Currently emitted as a string by the CCC pipeline." } } }, "description": "Historical rank samples for the row." }, "peakDate": { "type": [ "string", "null" ], "format": "date-time", "description": "Date the entity achieved its peak rank." }, "peakRank": { "type": [ "integer", "null" ], "description": "Best (lowest-numbered) rank achieved." }, "velocity7Day": { "type": [ "number", "null" ], "format": "float", "description": "7-day rank velocity (positive = trending up)." }, "periodsOnChart": { "type": [ "integer", "null" ], "description": "Total chart periods on the chart." }, "consecutivePeriods": { "type": [ "integer", "null" ], "description": "Consecutive chart periods without falling off." }, "chartedDate": { "type": [ "string", "null" ], "format": "date-time", "description": "Date of the chart row." }, "name": { "type": [ "string", "null" ], "description": "Entity name (track / album)." }, "imageUrl": { "type": [ "string", "null" ], "description": "Entity cover image URL." }, "createdAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Cache row creation timestamp." }, "artists": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ], "description": "Chartmetric artist ID." }, "name": { "type": [ "string", "null" ], "description": "Artist name." }, "code2": { "type": [ "string", "null" ], "description": "Artist country code (ISO 3166-1 alpha-2)." }, "careerStage": { "type": [ "string", "null" ], "description": "Artist career stage (e.g. `undiscovered`, `developing`, `mid-level`, `mainstream`, `superstar`, `legendary`)." }, "imageUrl": { "type": [ "string", "null" ], "description": "Artist image URL." } } }, "description": "Artists associated with the entity." }, "album": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "integer", "null" ], "description": "Chartmetric album ID." }, "name": { "type": [ "string", "null" ], "description": "Album name." }, "label": { "type": [ "string", "null" ], "description": "Album record label." }, "releaseDate": { "type": [ "string", "null" ], "format": "date-time", "description": "Album release date." } }, "description": "Album the entity belongs to (or the album itself for album charts)." }, "optionalRows": { "type": "object", "properties": { "overallRank": { "type": [ "number", "null" ], "format": "float", "description": "Overall ranking across the platform (legacy field)." }, "videos": { "type": [ "number", "null" ], "format": "float", "description": "Number of videos contributing to the row." }, "totalVideos": { "type": [ "number", "null" ], "format": "float", "description": "Total videos across the entity." }, "metricValue": { "type": [ "number", "null" ], "format": "float", "description": "Primary metric value driving the chart position." }, "metricDiff": { "type": [ "number", "null" ], "format": "float", "description": "Change in `metricValue` vs the previous period." }, "avgPosition": { "type": [ "number", "null" ], "format": "float", "description": "Average position over the chart window." }, "score": { "type": [ "number", "null" ], "format": "float", "description": "Score driving the chart position." }, "totalFollowers": { "type": [ "number", "null" ], "format": "float", "description": "Total followers across the entity." }, "velocity": { "type": [ "number", "null" ], "format": "float", "description": "Rank-velocity signal (positive = climbing)." }, "isComeback": { "type": [ "boolean", "null" ], "description": "True when the entity re-entered the chart after a break (comeback)." }, "plays": { "type": [ "number", "null" ], "format": "float", "description": "Play count contribution." }, "playsWeekly": { "type": [ "number", "null" ], "format": "float", "description": "Weekly play count." }, "counts": { "type": [ "number", "null" ], "format": "float", "description": "Generic count metric." }, "index": { "type": [ "number", "null" ], "format": "float", "description": "Generic chart index value." }, "comments": { "type": [ "number", "null" ], "format": "float", "description": "Comment count." }, "artistName": { "type": [ "string", "null" ], "description": "Primary artist name (legacy field)." }, "label": { "type": [ "string", "null" ], "description": "Album label (Hanteo physical-record charts)." }, "physicalRecordIndex": { "type": [ "string", "null" ], "description": "Hanteo physical-record index value." }, "albumName": { "type": [ "string", "null" ], "description": "Album name (legacy field)." }, "name": { "type": [ "string", "null" ], "description": "Entity name passthrough." }, "imageUrl": { "type": [ "string", "null" ], "description": "Image URL passthrough." }, "id": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Platform identifier (legacy passthrough)." }, "platformId": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Platform-specific external identifier." } }, "description": "Per-chart optional metrics (legacy name; populated on Melon/Hanteo/Circle/Line Music/Pandora/Anghami)." }, "optionalFields": { "type": "object", "properties": { "overallRank": { "type": [ "number", "null" ], "format": "float", "description": "Overall ranking across the platform (legacy field)." }, "videos": { "type": [ "number", "null" ], "format": "float", "description": "Number of videos contributing to the row." }, "totalVideos": { "type": [ "number", "null" ], "format": "float", "description": "Total videos across the entity." }, "metricValue": { "type": [ "number", "null" ], "format": "float", "description": "Primary metric value driving the chart position." }, "metricDiff": { "type": [ "number", "null" ], "format": "float", "description": "Change in `metricValue` vs the previous period." }, "avgPosition": { "type": [ "number", "null" ], "format": "float", "description": "Average position over the chart window." }, "score": { "type": [ "number", "null" ], "format": "float", "description": "Score driving the chart position." }, "totalFollowers": { "type": [ "number", "null" ], "format": "float", "description": "Total followers across the entity." }, "velocity": { "type": [ "number", "null" ], "format": "float", "description": "Rank-velocity signal (positive = climbing)." }, "isComeback": { "type": [ "boolean", "null" ], "description": "True when the entity re-entered the chart after a break (comeback)." }, "plays": { "type": [ "number", "null" ], "format": "float", "description": "Play count contribution." }, "playsWeekly": { "type": [ "number", "null" ], "format": "float", "description": "Weekly play count." }, "counts": { "type": [ "number", "null" ], "format": "float", "description": "Generic count metric." }, "index": { "type": [ "number", "null" ], "format": "float", "description": "Generic chart index value." }, "comments": { "type": [ "number", "null" ], "format": "float", "description": "Comment count." }, "artistName": { "type": [ "string", "null" ], "description": "Primary artist name (legacy field)." }, "label": { "type": [ "string", "null" ], "description": "Album label (Hanteo physical-record charts)." }, "physicalRecordIndex": { "type": [ "string", "null" ], "description": "Hanteo physical-record index value." }, "albumName": { "type": [ "string", "null" ], "description": "Album name (legacy field)." }, "name": { "type": [ "string", "null" ], "description": "Entity name passthrough." }, "imageUrl": { "type": [ "string", "null" ], "description": "Image URL passthrough." }, "id": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Platform identifier (legacy passthrough)." }, "platformId": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Platform-specific external identifier." } }, "description": "Per-chart optional metrics (used by the new SoundCloud chart and the hydrated TS row type)." }, "targetExtras": { "type": "object", "properties": { "airplayStreams": { "type": [ "number", "null" ], "format": "float", "description": "Airplay stream count snapshot." }, "amazonEdPlaylistCount": { "type": [ "number", "null" ], "format": "float", "description": "Number of Amazon editorial playlists containing the track." }, "amazonPlaylistCount": { "type": [ "number", "null" ], "format": "float", "description": "Number of Amazon playlists containing the track." }, "anghamiLikes": { "type": [ "number", "null" ], "format": "float", "description": "Anghami like count." }, "anghamiPlays": { "type": [ "number", "null" ], "format": "float", "description": "Anghami play count." }, "deezerEdPlaylistCount": { "type": [ "number", "null" ], "format": "float", "description": "Number of Deezer editorial playlists containing the track." }, "deezerEdPlaylistTotalReach": { "type": [ "number", "null" ], "format": "float", "description": "Total follower reach across Deezer editorial playlists." }, "deezerPlaylistCount": { "type": [ "number", "null" ], "format": "float", "description": "Number of Deezer playlists containing the track." }, "deezerPlaylistTotalReach": { "type": [ "number", "null" ], "format": "float", "description": "Total follower reach across Deezer playlists." }, "itunesEdPlaylistCount": { "type": [ "number", "null" ], "format": "float", "description": "Number of iTunes editorial playlists containing the track." }, "itunesPlaylistCount": { "type": [ "number", "null" ], "format": "float", "description": "Number of iTunes playlists containing the track." }, "lineMusicLikes": { "type": [ "number", "null" ], "format": "float", "description": "Line Music like count." }, "lineMusicListenCount": { "type": [ "number", "null" ], "format": "float", "description": "Line Music listen count." }, "melonComments": { "type": [ "number", "null" ], "format": "float", "description": "Melon comment count." }, "melonLikes": { "type": [ "number", "null" ], "format": "float", "description": "Melon like count." }, "pandoraLifetimeStationsAdded": { "type": [ "number", "null" ], "format": "float", "description": "Pandora lifetime station-additions count." }, "pandoraLifetimeStreams": { "type": [ "number", "null" ], "format": "float", "description": "Pandora lifetime stream count." }, "shazamCount": { "type": [ "number", "null" ], "format": "float", "description": "Shazam tag count." }, "siriusxmStreams": { "type": [ "number", "null" ], "format": "float", "description": "SiriusXM stream count." }, "soundcloudPlays": { "type": [ "number", "null" ], "format": "float", "description": "SoundCloud play count." }, "spotifyEdPlaylistCount": { "type": [ "number", "null" ], "format": "float", "description": "Number of Spotify editorial playlists containing the track." }, "spotifyEdPlaylistTotalReach": { "type": [ "number", "null" ], "format": "float", "description": "Total follower reach across Spotify editorial playlists." }, "spotifyPlaylistCount": { "type": [ "number", "null" ], "format": "float", "description": "Number of Spotify playlists containing the track." }, "spotifyPlaylistTotalReach": { "type": [ "number", "null" ], "format": "float", "description": "Total follower reach across Spotify playlists." }, "spotifyPlays": { "type": [ "number", "null" ], "format": "float", "description": "Spotify play count snapshot." }, "spotifyPopularity": { "type": [ "number", "null" ], "format": "float", "description": "Spotify popularity score (0–100)." }, "tiktokTopVideosComments": { "type": [ "number", "null" ], "format": "float", "description": "Comment count across the track's top TikTok videos." }, "tiktokTopVideosLikes": { "type": [ "number", "null" ], "format": "float", "description": "Like count across the track's top TikTok videos." }, "tiktokTopVideosViews": { "type": [ "number", "null" ], "format": "float", "description": "View count across the track's top TikTok videos." }, "youtubeComments": { "type": [ "number", "null" ], "format": "float", "description": "YouTube comment count." }, "youtubeEdPlaylistCount": { "type": [ "number", "null" ], "format": "float", "description": "Number of YouTube editorial playlists containing the track." }, "youtubeEdPlaylistTotalReach": { "type": [ "number", "null" ], "format": "float", "description": "Total follower reach across YouTube editorial playlists." }, "youtubeLikes": { "type": [ "number", "null" ], "format": "float", "description": "YouTube like count." }, "youtubePlaylistCount": { "type": [ "number", "null" ], "format": "float", "description": "Number of YouTube playlists containing the track." }, "youtubePlaylistTotalReach": { "type": [ "number", "null" ], "format": "float", "description": "Total follower reach across YouTube playlists." }, "youtubeViews": { "type": [ "number", "null" ], "format": "float", "description": "YouTube view count." } }, "description": "Cross-platform metric snapshots hydrated from per-target cache rows." }, "isChartGenre": { "type": [ "boolean", "null" ], "description": "True when the entity's genre matches the chart's genre filter." }, "externalId": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Platform external identifier (e.g. Hanteo internal index, SoundCloud track ID)." }, "externalUrl": { "type": [ "string", "null" ], "description": "Platform external URL." }, "isrc": { "type": [ "string", "null" ], "description": "International Standard Recording Code (SoundCloud chart only)." }, "entityGenre": { "type": [ "string", "null" ], "description": "Entity-level genre (when distinct from chart genre)." }, "id": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Numeric platform ID (Hanteo legacy field)." }, "platform_id": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Platform-side external ID (Hanteo legacy field)." } } }, "description": "List of regional chart rows." } }, "additionalProperties": false }, "examples": { "default": { "value": { "obj": [ { "entityId": 138071658, "targetId": "141653", "duration": "weekly", "country": "", "cityId": 0, "genre": "pop, k-pop, dance", "rank": 1, "rankDiff": 0, "rankTrend": [ { "timestp": "2025-03-16", "rank": "1" } ], "peakDate": "2024-10-20", "peakRank": 1, "velocity7Day": 0, "periodsOnChart": 33, "consecutivePeriods": 33, "chartedDate": "2025-05-25", "name": "APT.", "imageUrl": "https://i.scdn.co/image/ab67616d0000b27336032cb4acd9df050bc2e197", "createdAt": "2025-06-12T01:29:31.000Z", "artists": [ { "careerStage": "superstar", "code2": "KR", "id": 4114519, "name": "ROSÉ", "imageUrl": "https://i.scdn.co/image/ab6761610000e5ebcfb4350222919670128ff2dc" } ], "album": { "id": 39667137, "name": "APT.", "label": "Atlantic Records", "releaseDate": "2024-10-18T00:00:00.000Z" }, "externalId": 141653, "optionalRows": { "overallRank": 0, "score": 0, "isComeback": false }, "targetExtras": { "airplayStreams": 633819 }, "isChartGenre": true } ] } } } } } } } } }, "/api/charts/line_music/{entityType}/{chartType}": { "get": { "summary": "Line Music Chart", "tags": [ "Charts" ], "operationId": "getLineMusicCharts", "description": "Return Line Music chart entries for the given `entityType` (`track` or `album`). Shape matches the generic regional CCC chart row.", "parameters": [ { "name": "entityType", "in": "path", "schema": { "type": "string", "enum": [ "track", "album", "artist", "video" ], "description": "Chart entity (`track` or `album`)." }, "required": true, "description": "Chart entity (`track` or `album`).", "examples": { "default": { "value": "track" } } }, { "name": "chartType", "in": "path", "schema": { "type": "string", "enum": [ "top" ], "description": "Line Music chart type. Allowed values depend on `entityType`." }, "required": true, "description": "Line Music chart type. Allowed values depend on `entityType`.", "examples": { "default": { "value": "top" } } }, { "name": "date", "in": "query", "schema": { "type": "string", "format": "date", "description": "Date for the chart slice (`YYYY-MM-DD`). Required unless `latest=true`." }, "required": false, "description": "Date for the chart slice (`YYYY-MM-DD`). Required unless `latest=true`." }, { "name": "latest", "in": "query", "schema": { "type": "boolean", "description": "If true, use the most recently available chart date and ignore `date`.", "default": false }, "required": false, "description": "If true, use the most recently available chart date and ignore `date`." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "description": "Maximum number of items to return per request.", "default": 100 }, "required": false, "description": "Maximum number of items to return per request." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, "required": false, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, { "name": "code2", "in": "query", "schema": { "anyOf": [ { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB')." }, { "type": "string", "enum": [ "GLOBAL" ] } ], "description": "ISO 3166-1 alpha-2 country code (uppercase, e.g. 'US') or 'GLOBAL'. When omitted, the platform's default chart scope applies." }, "required": false, "description": "ISO 3166-1 alpha-2 country code (uppercase, e.g. 'US') or 'GLOBAL'. When omitted, the platform's default chart scope applies." }, { "name": "duration", "in": "query", "schema": { "type": "string", "enum": [ "daily", "monthly", "weekly", "yearly", "semi-yearly", "real-time", "all_time" ], "description": "Chart duration window. One of `daily`, `monthly`, `weekly`, `yearly`, `semi-yearly`, `real-time`, `all_time`." }, "required": true, "description": "Chart duration window. One of `daily`, `monthly`, `weekly`, `yearly`, `semi-yearly`, `real-time`, `all_time`.", "examples": { "default": { "value": "daily" } } }, { "name": "genre", "in": "query", "schema": { "type": "string", "maxLength": 100, "description": "Genre filter for the chart slice. Lowercased and trimmed." }, "required": false, "description": "Genre filter for the chart slice. Lowercased and trimmed." }, { "name": "cityId", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric city ID to scope the chart to a city." }, "required": false, "description": "Chartmetric city ID to scope the chart to a city." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "entityId": { "type": [ "integer", "null" ], "description": "Internal Chartmetric entity ID." }, "targetId": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Platform-side track / album / user ID." }, "duration": { "type": [ "string", "null" ], "description": "Chart duration window (e.g. `daily`, `weekly`, `monthly`)." }, "country": { "type": [ "string", "null" ], "description": "Chart country code (ISO 3166-1 alpha-2; empty string for non-country-scoped charts)." }, "cityId": { "type": [ "integer", "null" ], "description": "Chartmetric city ID, or 0 when not city-scoped." }, "genre": { "type": [ "string", "null" ], "description": "Chart genre." }, "rank": { "type": [ "integer", "null" ], "description": "Current chart rank (1 = top)." }, "rankDiff": { "type": [ "number", "null" ], "format": "float", "description": "Rank change from the previous period (negative = climbed)." }, "rankTrend": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "timestp": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp at which the rank was recorded." }, "rank": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Rank at `timestp` (1 = top). Currently emitted as a string by the CCC pipeline." } } }, "description": "Historical rank samples for the row." }, "peakDate": { "type": [ "string", "null" ], "format": "date-time", "description": "Date the entity achieved its peak rank." }, "peakRank": { "type": [ "integer", "null" ], "description": "Best (lowest-numbered) rank achieved." }, "velocity7Day": { "type": [ "number", "null" ], "format": "float", "description": "7-day rank velocity (positive = trending up)." }, "periodsOnChart": { "type": [ "integer", "null" ], "description": "Total chart periods on the chart." }, "consecutivePeriods": { "type": [ "integer", "null" ], "description": "Consecutive chart periods without falling off." }, "chartedDate": { "type": [ "string", "null" ], "format": "date-time", "description": "Date of the chart row." }, "name": { "type": [ "string", "null" ], "description": "Entity name (track / album)." }, "imageUrl": { "type": [ "string", "null" ], "description": "Entity cover image URL." }, "createdAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Cache row creation timestamp." }, "artists": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ], "description": "Chartmetric artist ID." }, "name": { "type": [ "string", "null" ], "description": "Artist name." }, "code2": { "type": [ "string", "null" ], "description": "Artist country code (ISO 3166-1 alpha-2)." }, "careerStage": { "type": [ "string", "null" ], "description": "Artist career stage (e.g. `undiscovered`, `developing`, `mid-level`, `mainstream`, `superstar`, `legendary`)." }, "imageUrl": { "type": [ "string", "null" ], "description": "Artist image URL." } } }, "description": "Artists associated with the entity." }, "album": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "integer", "null" ], "description": "Chartmetric album ID." }, "name": { "type": [ "string", "null" ], "description": "Album name." }, "label": { "type": [ "string", "null" ], "description": "Album record label." }, "releaseDate": { "type": [ "string", "null" ], "format": "date-time", "description": "Album release date." } }, "description": "Album the entity belongs to (or the album itself for album charts)." }, "optionalRows": { "type": "object", "properties": { "overallRank": { "type": [ "number", "null" ], "format": "float", "description": "Overall ranking across the platform (legacy field)." }, "videos": { "type": [ "number", "null" ], "format": "float", "description": "Number of videos contributing to the row." }, "totalVideos": { "type": [ "number", "null" ], "format": "float", "description": "Total videos across the entity." }, "metricValue": { "type": [ "number", "null" ], "format": "float", "description": "Primary metric value driving the chart position." }, "metricDiff": { "type": [ "number", "null" ], "format": "float", "description": "Change in `metricValue` vs the previous period." }, "avgPosition": { "type": [ "number", "null" ], "format": "float", "description": "Average position over the chart window." }, "score": { "type": [ "number", "null" ], "format": "float", "description": "Score driving the chart position." }, "totalFollowers": { "type": [ "number", "null" ], "format": "float", "description": "Total followers across the entity." }, "velocity": { "type": [ "number", "null" ], "format": "float", "description": "Rank-velocity signal (positive = climbing)." }, "isComeback": { "type": [ "boolean", "null" ], "description": "True when the entity re-entered the chart after a break (comeback)." }, "plays": { "type": [ "number", "null" ], "format": "float", "description": "Play count contribution." }, "playsWeekly": { "type": [ "number", "null" ], "format": "float", "description": "Weekly play count." }, "counts": { "type": [ "number", "null" ], "format": "float", "description": "Generic count metric." }, "index": { "type": [ "number", "null" ], "format": "float", "description": "Generic chart index value." }, "comments": { "type": [ "number", "null" ], "format": "float", "description": "Comment count." }, "artistName": { "type": [ "string", "null" ], "description": "Primary artist name (legacy field)." }, "label": { "type": [ "string", "null" ], "description": "Album label (Hanteo physical-record charts)." }, "physicalRecordIndex": { "type": [ "string", "null" ], "description": "Hanteo physical-record index value." }, "albumName": { "type": [ "string", "null" ], "description": "Album name (legacy field)." }, "name": { "type": [ "string", "null" ], "description": "Entity name passthrough." }, "imageUrl": { "type": [ "string", "null" ], "description": "Image URL passthrough." }, "id": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Platform identifier (legacy passthrough)." }, "platformId": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Platform-specific external identifier." } }, "description": "Per-chart optional metrics (legacy name; populated on Melon/Hanteo/Circle/Line Music/Pandora/Anghami)." }, "optionalFields": { "type": "object", "properties": { "overallRank": { "type": [ "number", "null" ], "format": "float", "description": "Overall ranking across the platform (legacy field)." }, "videos": { "type": [ "number", "null" ], "format": "float", "description": "Number of videos contributing to the row." }, "totalVideos": { "type": [ "number", "null" ], "format": "float", "description": "Total videos across the entity." }, "metricValue": { "type": [ "number", "null" ], "format": "float", "description": "Primary metric value driving the chart position." }, "metricDiff": { "type": [ "number", "null" ], "format": "float", "description": "Change in `metricValue` vs the previous period." }, "avgPosition": { "type": [ "number", "null" ], "format": "float", "description": "Average position over the chart window." }, "score": { "type": [ "number", "null" ], "format": "float", "description": "Score driving the chart position." }, "totalFollowers": { "type": [ "number", "null" ], "format": "float", "description": "Total followers across the entity." }, "velocity": { "type": [ "number", "null" ], "format": "float", "description": "Rank-velocity signal (positive = climbing)." }, "isComeback": { "type": [ "boolean", "null" ], "description": "True when the entity re-entered the chart after a break (comeback)." }, "plays": { "type": [ "number", "null" ], "format": "float", "description": "Play count contribution." }, "playsWeekly": { "type": [ "number", "null" ], "format": "float", "description": "Weekly play count." }, "counts": { "type": [ "number", "null" ], "format": "float", "description": "Generic count metric." }, "index": { "type": [ "number", "null" ], "format": "float", "description": "Generic chart index value." }, "comments": { "type": [ "number", "null" ], "format": "float", "description": "Comment count." }, "artistName": { "type": [ "string", "null" ], "description": "Primary artist name (legacy field)." }, "label": { "type": [ "string", "null" ], "description": "Album label (Hanteo physical-record charts)." }, "physicalRecordIndex": { "type": [ "string", "null" ], "description": "Hanteo physical-record index value." }, "albumName": { "type": [ "string", "null" ], "description": "Album name (legacy field)." }, "name": { "type": [ "string", "null" ], "description": "Entity name passthrough." }, "imageUrl": { "type": [ "string", "null" ], "description": "Image URL passthrough." }, "id": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Platform identifier (legacy passthrough)." }, "platformId": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Platform-specific external identifier." } }, "description": "Per-chart optional metrics (used by the new SoundCloud chart and the hydrated TS row type)." }, "targetExtras": { "type": "object", "properties": { "airplayStreams": { "type": [ "number", "null" ], "format": "float", "description": "Airplay stream count snapshot." }, "amazonEdPlaylistCount": { "type": [ "number", "null" ], "format": "float", "description": "Number of Amazon editorial playlists containing the track." }, "amazonPlaylistCount": { "type": [ "number", "null" ], "format": "float", "description": "Number of Amazon playlists containing the track." }, "anghamiLikes": { "type": [ "number", "null" ], "format": "float", "description": "Anghami like count." }, "anghamiPlays": { "type": [ "number", "null" ], "format": "float", "description": "Anghami play count." }, "deezerEdPlaylistCount": { "type": [ "number", "null" ], "format": "float", "description": "Number of Deezer editorial playlists containing the track." }, "deezerEdPlaylistTotalReach": { "type": [ "number", "null" ], "format": "float", "description": "Total follower reach across Deezer editorial playlists." }, "deezerPlaylistCount": { "type": [ "number", "null" ], "format": "float", "description": "Number of Deezer playlists containing the track." }, "deezerPlaylistTotalReach": { "type": [ "number", "null" ], "format": "float", "description": "Total follower reach across Deezer playlists." }, "itunesEdPlaylistCount": { "type": [ "number", "null" ], "format": "float", "description": "Number of iTunes editorial playlists containing the track." }, "itunesPlaylistCount": { "type": [ "number", "null" ], "format": "float", "description": "Number of iTunes playlists containing the track." }, "lineMusicLikes": { "type": [ "number", "null" ], "format": "float", "description": "Line Music like count." }, "lineMusicListenCount": { "type": [ "number", "null" ], "format": "float", "description": "Line Music listen count." }, "melonComments": { "type": [ "number", "null" ], "format": "float", "description": "Melon comment count." }, "melonLikes": { "type": [ "number", "null" ], "format": "float", "description": "Melon like count." }, "pandoraLifetimeStationsAdded": { "type": [ "number", "null" ], "format": "float", "description": "Pandora lifetime station-additions count." }, "pandoraLifetimeStreams": { "type": [ "number", "null" ], "format": "float", "description": "Pandora lifetime stream count." }, "shazamCount": { "type": [ "number", "null" ], "format": "float", "description": "Shazam tag count." }, "siriusxmStreams": { "type": [ "number", "null" ], "format": "float", "description": "SiriusXM stream count." }, "soundcloudPlays": { "type": [ "number", "null" ], "format": "float", "description": "SoundCloud play count." }, "spotifyEdPlaylistCount": { "type": [ "number", "null" ], "format": "float", "description": "Number of Spotify editorial playlists containing the track." }, "spotifyEdPlaylistTotalReach": { "type": [ "number", "null" ], "format": "float", "description": "Total follower reach across Spotify editorial playlists." }, "spotifyPlaylistCount": { "type": [ "number", "null" ], "format": "float", "description": "Number of Spotify playlists containing the track." }, "spotifyPlaylistTotalReach": { "type": [ "number", "null" ], "format": "float", "description": "Total follower reach across Spotify playlists." }, "spotifyPlays": { "type": [ "number", "null" ], "format": "float", "description": "Spotify play count snapshot." }, "spotifyPopularity": { "type": [ "number", "null" ], "format": "float", "description": "Spotify popularity score (0–100)." }, "tiktokTopVideosComments": { "type": [ "number", "null" ], "format": "float", "description": "Comment count across the track's top TikTok videos." }, "tiktokTopVideosLikes": { "type": [ "number", "null" ], "format": "float", "description": "Like count across the track's top TikTok videos." }, "tiktokTopVideosViews": { "type": [ "number", "null" ], "format": "float", "description": "View count across the track's top TikTok videos." }, "youtubeComments": { "type": [ "number", "null" ], "format": "float", "description": "YouTube comment count." }, "youtubeEdPlaylistCount": { "type": [ "number", "null" ], "format": "float", "description": "Number of YouTube editorial playlists containing the track." }, "youtubeEdPlaylistTotalReach": { "type": [ "number", "null" ], "format": "float", "description": "Total follower reach across YouTube editorial playlists." }, "youtubeLikes": { "type": [ "number", "null" ], "format": "float", "description": "YouTube like count." }, "youtubePlaylistCount": { "type": [ "number", "null" ], "format": "float", "description": "Number of YouTube playlists containing the track." }, "youtubePlaylistTotalReach": { "type": [ "number", "null" ], "format": "float", "description": "Total follower reach across YouTube playlists." }, "youtubeViews": { "type": [ "number", "null" ], "format": "float", "description": "YouTube view count." } }, "description": "Cross-platform metric snapshots hydrated from per-target cache rows." }, "isChartGenre": { "type": [ "boolean", "null" ], "description": "True when the entity's genre matches the chart's genre filter." }, "externalId": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Platform external identifier (e.g. Hanteo internal index, SoundCloud track ID)." }, "externalUrl": { "type": [ "string", "null" ], "description": "Platform external URL." }, "isrc": { "type": [ "string", "null" ], "description": "International Standard Recording Code (SoundCloud chart only)." }, "entityGenre": { "type": [ "string", "null" ], "description": "Entity-level genre (when distinct from chart genre)." }, "id": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Numeric platform ID (Hanteo legacy field)." }, "platform_id": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Platform-side external ID (Hanteo legacy field)." } } }, "description": "List of regional chart rows." } }, "additionalProperties": false }, "examples": { "default": { "value": { "obj": [ { "entityId": 142483816, "targetId": "mt0000000020d08f07", "duration": "daily", "country": "", "cityId": 0, "genre": "Anime", "rank": 1, "rankDiff": 0, "rankTrend": [ { "timestp": "2025-05-31", "rank": "1" } ], "peakDate": "2025-04-06", "peakRank": 1, "velocity7Day": 0, "periodsOnChart": 76, "consecutivePeriods": 76, "chartedDate": "2025-06-03", "name": "Song title", "imageUrl": "https://i.scdn.co/image/ab67616d0000b2734840f84e07ee7e34a6414896", "createdAt": "2025-06-09T02:06:42.000Z", "artists": [ { "careerStage": "mainstream", "code2": "JP", "id": 13330465, "name": "AiScReam", "imageUrl": "https://i.scdn.co/image/ab6761610000e5ebda8783293aa77cd94d11f8b7" } ], "album": { "id": 44252905, "name": "Album title", "label": "Lantis", "releaseDate": "2025-01-21T00:00:00.000Z" }, "optionalRows": { "overallRank": 0, "score": 0, "isComeback": false }, "targetExtras": { "lineMusicLikes": 20884, "lineMusicListenCount": 1334992 }, "isChartGenre": true } ] } } } } } } } } }, "/api/charts/pandora/track/{chartType}": { "get": { "summary": "Pandora Track Chart", "tags": [ "Charts" ], "operationId": "getPandoraTrackCharts", "description": "Return Pandora track chart entries. Served by the CCC (`cm_chart_cache_v2`) pipeline.", "parameters": [ { "name": "chartType", "in": "path", "schema": { "type": "string", "enum": [ "top_thumb_hundred", "top_spins" ], "description": "Pandora track chart type (e.g. `top_spins`, `top_thumbs`)." }, "required": true, "description": "Pandora track chart type (e.g. `top_spins`, `top_thumbs`).", "examples": { "default": { "value": "top_thumb_hundred" } } }, { "name": "date", "in": "query", "schema": { "type": "string", "format": "date", "description": "Date for the chart slice (`YYYY-MM-DD`). Required unless `latest=true`." }, "required": false, "description": "Date for the chart slice (`YYYY-MM-DD`). Required unless `latest=true`." }, { "name": "latest", "in": "query", "schema": { "type": "boolean", "description": "If true, use the most recently available chart date and ignore `date`.", "default": false }, "required": false, "description": "If true, use the most recently available chart date and ignore `date`." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "description": "Maximum number of items to return per request.", "default": 100 }, "required": false, "description": "Maximum number of items to return per request." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, "required": false, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, { "name": "code2", "in": "query", "schema": { "anyOf": [ { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB')." }, { "type": "string", "enum": [ "GLOBAL" ] } ], "description": "ISO 3166-1 alpha-2 country code (uppercase, e.g. 'US') or 'GLOBAL'. When omitted, the platform's default chart scope applies." }, "required": false, "description": "ISO 3166-1 alpha-2 country code (uppercase, e.g. 'US') or 'GLOBAL'. When omitted, the platform's default chart scope applies." }, { "name": "duration", "in": "query", "schema": { "type": "string", "enum": [ "daily", "monthly", "weekly", "yearly", "semi-yearly", "real-time", "all_time" ], "description": "Chart duration window. One of `daily`, `monthly`, `weekly`, `yearly`, `semi-yearly`, `real-time`, `all_time`." }, "required": false, "description": "Chart duration window. One of `daily`, `monthly`, `weekly`, `yearly`, `semi-yearly`, `real-time`, `all_time`." }, { "name": "genre", "in": "query", "schema": { "type": "string", "maxLength": 100, "description": "Genre filter for the chart slice. Lowercased and trimmed." }, "required": false, "description": "Genre filter for the chart slice. Lowercased and trimmed." }, { "name": "cityId", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric city ID to scope the chart to a city." }, "required": false, "description": "Chartmetric city ID to scope the chart to a city." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "entityId": { "type": [ "integer", "null" ], "description": "Internal Chartmetric entity ID." }, "targetId": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Platform-side track / album / user ID." }, "duration": { "type": [ "string", "null" ], "description": "Chart duration window (e.g. `daily`, `weekly`, `monthly`)." }, "country": { "type": [ "string", "null" ], "description": "Chart country code (ISO 3166-1 alpha-2; empty string for non-country-scoped charts)." }, "cityId": { "type": [ "integer", "null" ], "description": "Chartmetric city ID, or 0 when not city-scoped." }, "genre": { "type": [ "string", "null" ], "description": "Chart genre." }, "rank": { "type": [ "integer", "null" ], "description": "Current chart rank (1 = top)." }, "rankDiff": { "type": [ "number", "null" ], "format": "float", "description": "Rank change from the previous period (negative = climbed)." }, "rankTrend": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "timestp": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp at which the rank was recorded." }, "rank": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Rank at `timestp` (1 = top). Currently emitted as a string by the CCC pipeline." } } }, "description": "Historical rank samples for the row." }, "peakDate": { "type": [ "string", "null" ], "format": "date-time", "description": "Date the entity achieved its peak rank." }, "peakRank": { "type": [ "integer", "null" ], "description": "Best (lowest-numbered) rank achieved." }, "velocity7Day": { "type": [ "number", "null" ], "format": "float", "description": "7-day rank velocity (positive = trending up)." }, "periodsOnChart": { "type": [ "integer", "null" ], "description": "Total chart periods on the chart." }, "consecutivePeriods": { "type": [ "integer", "null" ], "description": "Consecutive chart periods without falling off." }, "chartedDate": { "type": [ "string", "null" ], "format": "date-time", "description": "Date of the chart row." }, "name": { "type": [ "string", "null" ], "description": "Entity name (track / album)." }, "imageUrl": { "type": [ "string", "null" ], "description": "Entity cover image URL." }, "createdAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Cache row creation timestamp." }, "artists": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ], "description": "Chartmetric artist ID." }, "name": { "type": [ "string", "null" ], "description": "Artist name." }, "code2": { "type": [ "string", "null" ], "description": "Artist country code (ISO 3166-1 alpha-2)." }, "careerStage": { "type": [ "string", "null" ], "description": "Artist career stage (e.g. `undiscovered`, `developing`, `mid-level`, `mainstream`, `superstar`, `legendary`)." }, "imageUrl": { "type": [ "string", "null" ], "description": "Artist image URL." } } }, "description": "Artists associated with the entity." }, "album": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "integer", "null" ], "description": "Chartmetric album ID." }, "name": { "type": [ "string", "null" ], "description": "Album name." }, "label": { "type": [ "string", "null" ], "description": "Album record label." }, "releaseDate": { "type": [ "string", "null" ], "format": "date-time", "description": "Album release date." } }, "description": "Album the entity belongs to (or the album itself for album charts)." }, "optionalRows": { "type": "object", "properties": { "overallRank": { "type": [ "number", "null" ], "format": "float", "description": "Overall ranking across the platform (legacy field)." }, "videos": { "type": [ "number", "null" ], "format": "float", "description": "Number of videos contributing to the row." }, "totalVideos": { "type": [ "number", "null" ], "format": "float", "description": "Total videos across the entity." }, "metricValue": { "type": [ "number", "null" ], "format": "float", "description": "Primary metric value driving the chart position." }, "metricDiff": { "type": [ "number", "null" ], "format": "float", "description": "Change in `metricValue` vs the previous period." }, "avgPosition": { "type": [ "number", "null" ], "format": "float", "description": "Average position over the chart window." }, "score": { "type": [ "number", "null" ], "format": "float", "description": "Score driving the chart position." }, "totalFollowers": { "type": [ "number", "null" ], "format": "float", "description": "Total followers across the entity." }, "velocity": { "type": [ "number", "null" ], "format": "float", "description": "Rank-velocity signal (positive = climbing)." }, "isComeback": { "type": [ "boolean", "null" ], "description": "True when the entity re-entered the chart after a break (comeback)." }, "plays": { "type": [ "number", "null" ], "format": "float", "description": "Play count contribution." }, "playsWeekly": { "type": [ "number", "null" ], "format": "float", "description": "Weekly play count." }, "counts": { "type": [ "number", "null" ], "format": "float", "description": "Generic count metric." }, "index": { "type": [ "number", "null" ], "format": "float", "description": "Generic chart index value." }, "comments": { "type": [ "number", "null" ], "format": "float", "description": "Comment count." }, "artistName": { "type": [ "string", "null" ], "description": "Primary artist name (legacy field)." }, "label": { "type": [ "string", "null" ], "description": "Album label (Hanteo physical-record charts)." }, "physicalRecordIndex": { "type": [ "string", "null" ], "description": "Hanteo physical-record index value." }, "albumName": { "type": [ "string", "null" ], "description": "Album name (legacy field)." }, "name": { "type": [ "string", "null" ], "description": "Entity name passthrough." }, "imageUrl": { "type": [ "string", "null" ], "description": "Image URL passthrough." }, "id": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Platform identifier (legacy passthrough)." }, "platformId": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Platform-specific external identifier." } }, "description": "Per-chart optional metrics (legacy name; populated on Melon/Hanteo/Circle/Line Music/Pandora/Anghami)." }, "optionalFields": { "type": "object", "properties": { "overallRank": { "type": [ "number", "null" ], "format": "float", "description": "Overall ranking across the platform (legacy field)." }, "videos": { "type": [ "number", "null" ], "format": "float", "description": "Number of videos contributing to the row." }, "totalVideos": { "type": [ "number", "null" ], "format": "float", "description": "Total videos across the entity." }, "metricValue": { "type": [ "number", "null" ], "format": "float", "description": "Primary metric value driving the chart position." }, "metricDiff": { "type": [ "number", "null" ], "format": "float", "description": "Change in `metricValue` vs the previous period." }, "avgPosition": { "type": [ "number", "null" ], "format": "float", "description": "Average position over the chart window." }, "score": { "type": [ "number", "null" ], "format": "float", "description": "Score driving the chart position." }, "totalFollowers": { "type": [ "number", "null" ], "format": "float", "description": "Total followers across the entity." }, "velocity": { "type": [ "number", "null" ], "format": "float", "description": "Rank-velocity signal (positive = climbing)." }, "isComeback": { "type": [ "boolean", "null" ], "description": "True when the entity re-entered the chart after a break (comeback)." }, "plays": { "type": [ "number", "null" ], "format": "float", "description": "Play count contribution." }, "playsWeekly": { "type": [ "number", "null" ], "format": "float", "description": "Weekly play count." }, "counts": { "type": [ "number", "null" ], "format": "float", "description": "Generic count metric." }, "index": { "type": [ "number", "null" ], "format": "float", "description": "Generic chart index value." }, "comments": { "type": [ "number", "null" ], "format": "float", "description": "Comment count." }, "artistName": { "type": [ "string", "null" ], "description": "Primary artist name (legacy field)." }, "label": { "type": [ "string", "null" ], "description": "Album label (Hanteo physical-record charts)." }, "physicalRecordIndex": { "type": [ "string", "null" ], "description": "Hanteo physical-record index value." }, "albumName": { "type": [ "string", "null" ], "description": "Album name (legacy field)." }, "name": { "type": [ "string", "null" ], "description": "Entity name passthrough." }, "imageUrl": { "type": [ "string", "null" ], "description": "Image URL passthrough." }, "id": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Platform identifier (legacy passthrough)." }, "platformId": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Platform-specific external identifier." } }, "description": "Per-chart optional metrics (used by the new SoundCloud chart and the hydrated TS row type)." }, "targetExtras": { "type": "object", "properties": { "airplayStreams": { "type": [ "number", "null" ], "format": "float", "description": "Airplay stream count snapshot." }, "amazonEdPlaylistCount": { "type": [ "number", "null" ], "format": "float", "description": "Number of Amazon editorial playlists containing the track." }, "amazonPlaylistCount": { "type": [ "number", "null" ], "format": "float", "description": "Number of Amazon playlists containing the track." }, "anghamiLikes": { "type": [ "number", "null" ], "format": "float", "description": "Anghami like count." }, "anghamiPlays": { "type": [ "number", "null" ], "format": "float", "description": "Anghami play count." }, "deezerEdPlaylistCount": { "type": [ "number", "null" ], "format": "float", "description": "Number of Deezer editorial playlists containing the track." }, "deezerEdPlaylistTotalReach": { "type": [ "number", "null" ], "format": "float", "description": "Total follower reach across Deezer editorial playlists." }, "deezerPlaylistCount": { "type": [ "number", "null" ], "format": "float", "description": "Number of Deezer playlists containing the track." }, "deezerPlaylistTotalReach": { "type": [ "number", "null" ], "format": "float", "description": "Total follower reach across Deezer playlists." }, "itunesEdPlaylistCount": { "type": [ "number", "null" ], "format": "float", "description": "Number of iTunes editorial playlists containing the track." }, "itunesPlaylistCount": { "type": [ "number", "null" ], "format": "float", "description": "Number of iTunes playlists containing the track." }, "lineMusicLikes": { "type": [ "number", "null" ], "format": "float", "description": "Line Music like count." }, "lineMusicListenCount": { "type": [ "number", "null" ], "format": "float", "description": "Line Music listen count." }, "melonComments": { "type": [ "number", "null" ], "format": "float", "description": "Melon comment count." }, "melonLikes": { "type": [ "number", "null" ], "format": "float", "description": "Melon like count." }, "pandoraLifetimeStationsAdded": { "type": [ "number", "null" ], "format": "float", "description": "Pandora lifetime station-additions count." }, "pandoraLifetimeStreams": { "type": [ "number", "null" ], "format": "float", "description": "Pandora lifetime stream count." }, "shazamCount": { "type": [ "number", "null" ], "format": "float", "description": "Shazam tag count." }, "siriusxmStreams": { "type": [ "number", "null" ], "format": "float", "description": "SiriusXM stream count." }, "soundcloudPlays": { "type": [ "number", "null" ], "format": "float", "description": "SoundCloud play count." }, "spotifyEdPlaylistCount": { "type": [ "number", "null" ], "format": "float", "description": "Number of Spotify editorial playlists containing the track." }, "spotifyEdPlaylistTotalReach": { "type": [ "number", "null" ], "format": "float", "description": "Total follower reach across Spotify editorial playlists." }, "spotifyPlaylistCount": { "type": [ "number", "null" ], "format": "float", "description": "Number of Spotify playlists containing the track." }, "spotifyPlaylistTotalReach": { "type": [ "number", "null" ], "format": "float", "description": "Total follower reach across Spotify playlists." }, "spotifyPlays": { "type": [ "number", "null" ], "format": "float", "description": "Spotify play count snapshot." }, "spotifyPopularity": { "type": [ "number", "null" ], "format": "float", "description": "Spotify popularity score (0–100)." }, "tiktokTopVideosComments": { "type": [ "number", "null" ], "format": "float", "description": "Comment count across the track's top TikTok videos." }, "tiktokTopVideosLikes": { "type": [ "number", "null" ], "format": "float", "description": "Like count across the track's top TikTok videos." }, "tiktokTopVideosViews": { "type": [ "number", "null" ], "format": "float", "description": "View count across the track's top TikTok videos." }, "youtubeComments": { "type": [ "number", "null" ], "format": "float", "description": "YouTube comment count." }, "youtubeEdPlaylistCount": { "type": [ "number", "null" ], "format": "float", "description": "Number of YouTube editorial playlists containing the track." }, "youtubeEdPlaylistTotalReach": { "type": [ "number", "null" ], "format": "float", "description": "Total follower reach across YouTube editorial playlists." }, "youtubeLikes": { "type": [ "number", "null" ], "format": "float", "description": "YouTube like count." }, "youtubePlaylistCount": { "type": [ "number", "null" ], "format": "float", "description": "Number of YouTube playlists containing the track." }, "youtubePlaylistTotalReach": { "type": [ "number", "null" ], "format": "float", "description": "Total follower reach across YouTube playlists." }, "youtubeViews": { "type": [ "number", "null" ], "format": "float", "description": "YouTube view count." } }, "description": "Cross-platform metric snapshots hydrated from per-target cache rows." }, "isChartGenre": { "type": [ "boolean", "null" ], "description": "True when the entity's genre matches the chart's genre filter." }, "externalId": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Platform external identifier (e.g. Hanteo internal index, SoundCloud track ID)." }, "externalUrl": { "type": [ "string", "null" ], "description": "Platform external URL." }, "isrc": { "type": [ "string", "null" ], "description": "International Standard Recording Code (SoundCloud chart only)." }, "entityGenre": { "type": [ "string", "null" ], "description": "Entity-level genre (when distinct from chart genre)." }, "id": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Numeric platform ID (Hanteo legacy field)." }, "platform_id": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Platform-side external ID (Hanteo legacy field)." } } }, "description": "List of regional chart rows." } }, "additionalProperties": false }, "examples": { "default": { "value": { "obj": [ { "entityId": 142829508, "targetId": "S159745474", "country": "", "cityId": 0, "genre": "country, alternative, pop", "rank": 1, "rankDiff": 0, "rankTrend": [ { "timestp": "2025-06-05", "rank": "1" } ], "peakDate": "2025-05-29", "peakRank": 1, "velocity7Day": 0, "periodsOnChart": 22, "consecutivePeriods": 5, "chartedDate": "2025-06-26", "name": "I'm The Problem", "imageUrl": "https://i.scdn.co/image/ab67616d0000b273985da65c010002691e5ba05a", "createdAt": "2025-07-04T20:12:44.000Z", "artists": [ { "careerStage": "superstar", "code2": "US", "id": 212715, "name": "Morgan Wallen", "imageUrl": "https://i.scdn.co/image/ab6761610000e5eb4245b1652fcc23f2b76ccd07" } ], "album": { "id": 42059519, "name": "I'm The Problem", "label": "Big Loud Records / Mercury Records / Republic Records", "releaseDate": "2025-01-31T00:00:00.000Z" }, "optionalRows": { "artistName": "Morgan Wallen", "overallRank": 0, "score": 3075628, "isComeback": false }, "targetExtras": { "pandoraLifetimeStationsAdded": 20796, "pandoraLifetimeStreams": 79701790 }, "isChartGenre": true } ] } } } } } } } } }, "/api/charts/anghami/track/{chartType}": { "get": { "summary": "Anghami Track Chart", "tags": [ "Charts" ], "operationId": "getAnghamiTrackCharts", "description": "Return Anghami track chart entries. `chartType` accepts `play` or `like`. Anghami stores both genre and country charts in a single table, so the handler defaults `code2` to `00` (global) and `genre` to `all genres` when unspecified. A single request may use either `genre` or `code2`, not both.", "parameters": [ { "name": "chartType", "in": "path", "schema": { "type": "string", "enum": [ "play", "like" ], "description": "Anghami track chart type (e.g. `play`, `like`)." }, "required": true, "description": "Anghami track chart type (e.g. `play`, `like`).", "examples": { "default": { "value": "play" } } }, { "name": "date", "in": "query", "schema": { "type": "string", "format": "date", "description": "Date for the chart slice (`YYYY-MM-DD`). Required unless `latest=true`." }, "required": false, "description": "Date for the chart slice (`YYYY-MM-DD`). Required unless `latest=true`." }, { "name": "latest", "in": "query", "schema": { "type": "boolean", "description": "If true, use the most recently available chart date and ignore `date`.", "default": false }, "required": false, "description": "If true, use the most recently available chart date and ignore `date`." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "description": "Maximum number of items to return per request.", "default": 100 }, "required": false, "description": "Maximum number of items to return per request." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, "required": false, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, { "name": "code2", "in": "query", "schema": { "anyOf": [ { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB')." }, { "type": "string", "enum": [ "GLOBAL" ] } ], "description": "ISO 3166-1 alpha-2 country code (uppercase, e.g. 'US') or 'GLOBAL'. When omitted, the platform's default chart scope applies." }, "required": true, "description": "ISO 3166-1 alpha-2 country code (uppercase, e.g. 'US') or 'GLOBAL'. When omitted, the platform's default chart scope applies.", "examples": { "default": { "value": "US" } } }, { "name": "duration", "in": "query", "schema": { "type": "string", "enum": [ "daily", "monthly", "weekly", "yearly", "semi-yearly", "real-time", "all_time" ], "description": "Chart duration window. One of `daily`, `monthly`, `weekly`, `yearly`, `semi-yearly`, `real-time`, `all_time`." }, "required": false, "description": "Chart duration window. One of `daily`, `monthly`, `weekly`, `yearly`, `semi-yearly`, `real-time`, `all_time`." }, { "name": "genre", "in": "query", "schema": { "type": "string", "maxLength": 100, "description": "Genre filter for the chart slice. Lowercased and trimmed." }, "required": true, "description": "Genre filter for the chart slice. Lowercased and trimmed.", "examples": { "default": { "value": "example" } } }, { "name": "cityId", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric city ID to scope the chart to a city." }, "required": false, "description": "Chartmetric city ID to scope the chart to a city." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "entityId": { "type": [ "integer", "null" ], "description": "Internal Chartmetric entity ID." }, "targetId": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Platform-side track / album / user ID." }, "duration": { "type": [ "string", "null" ], "description": "Chart duration window (e.g. `daily`, `weekly`, `monthly`)." }, "country": { "type": [ "string", "null" ], "description": "Chart country code (ISO 3166-1 alpha-2; empty string for non-country-scoped charts)." }, "cityId": { "type": [ "integer", "null" ], "description": "Chartmetric city ID, or 0 when not city-scoped." }, "genre": { "type": [ "string", "null" ], "description": "Chart genre." }, "rank": { "type": [ "integer", "null" ], "description": "Current chart rank (1 = top)." }, "rankDiff": { "type": [ "number", "null" ], "format": "float", "description": "Rank change from the previous period (negative = climbed)." }, "rankTrend": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "timestp": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp at which the rank was recorded." }, "rank": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Rank at `timestp` (1 = top). Currently emitted as a string by the CCC pipeline." } } }, "description": "Historical rank samples for the row." }, "peakDate": { "type": [ "string", "null" ], "format": "date-time", "description": "Date the entity achieved its peak rank." }, "peakRank": { "type": [ "integer", "null" ], "description": "Best (lowest-numbered) rank achieved." }, "velocity7Day": { "type": [ "number", "null" ], "format": "float", "description": "7-day rank velocity (positive = trending up)." }, "periodsOnChart": { "type": [ "integer", "null" ], "description": "Total chart periods on the chart." }, "consecutivePeriods": { "type": [ "integer", "null" ], "description": "Consecutive chart periods without falling off." }, "chartedDate": { "type": [ "string", "null" ], "format": "date-time", "description": "Date of the chart row." }, "name": { "type": [ "string", "null" ], "description": "Entity name (track / album)." }, "imageUrl": { "type": [ "string", "null" ], "description": "Entity cover image URL." }, "createdAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Cache row creation timestamp." }, "artists": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ], "description": "Chartmetric artist ID." }, "name": { "type": [ "string", "null" ], "description": "Artist name." }, "code2": { "type": [ "string", "null" ], "description": "Artist country code (ISO 3166-1 alpha-2)." }, "careerStage": { "type": [ "string", "null" ], "description": "Artist career stage (e.g. `undiscovered`, `developing`, `mid-level`, `mainstream`, `superstar`, `legendary`)." }, "imageUrl": { "type": [ "string", "null" ], "description": "Artist image URL." } } }, "description": "Artists associated with the entity." }, "album": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "integer", "null" ], "description": "Chartmetric album ID." }, "name": { "type": [ "string", "null" ], "description": "Album name." }, "label": { "type": [ "string", "null" ], "description": "Album record label." }, "releaseDate": { "type": [ "string", "null" ], "format": "date-time", "description": "Album release date." } }, "description": "Album the entity belongs to (or the album itself for album charts)." }, "optionalRows": { "type": "object", "properties": { "overallRank": { "type": [ "number", "null" ], "format": "float", "description": "Overall ranking across the platform (legacy field)." }, "videos": { "type": [ "number", "null" ], "format": "float", "description": "Number of videos contributing to the row." }, "totalVideos": { "type": [ "number", "null" ], "format": "float", "description": "Total videos across the entity." }, "metricValue": { "type": [ "number", "null" ], "format": "float", "description": "Primary metric value driving the chart position." }, "metricDiff": { "type": [ "number", "null" ], "format": "float", "description": "Change in `metricValue` vs the previous period." }, "avgPosition": { "type": [ "number", "null" ], "format": "float", "description": "Average position over the chart window." }, "score": { "type": [ "number", "null" ], "format": "float", "description": "Score driving the chart position." }, "totalFollowers": { "type": [ "number", "null" ], "format": "float", "description": "Total followers across the entity." }, "velocity": { "type": [ "number", "null" ], "format": "float", "description": "Rank-velocity signal (positive = climbing)." }, "isComeback": { "type": [ "boolean", "null" ], "description": "True when the entity re-entered the chart after a break (comeback)." }, "plays": { "type": [ "number", "null" ], "format": "float", "description": "Play count contribution." }, "playsWeekly": { "type": [ "number", "null" ], "format": "float", "description": "Weekly play count." }, "counts": { "type": [ "number", "null" ], "format": "float", "description": "Generic count metric." }, "index": { "type": [ "number", "null" ], "format": "float", "description": "Generic chart index value." }, "comments": { "type": [ "number", "null" ], "format": "float", "description": "Comment count." }, "artistName": { "type": [ "string", "null" ], "description": "Primary artist name (legacy field)." }, "label": { "type": [ "string", "null" ], "description": "Album label (Hanteo physical-record charts)." }, "physicalRecordIndex": { "type": [ "string", "null" ], "description": "Hanteo physical-record index value." }, "albumName": { "type": [ "string", "null" ], "description": "Album name (legacy field)." }, "name": { "type": [ "string", "null" ], "description": "Entity name passthrough." }, "imageUrl": { "type": [ "string", "null" ], "description": "Image URL passthrough." }, "id": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Platform identifier (legacy passthrough)." }, "platformId": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Platform-specific external identifier." } }, "description": "Per-chart optional metrics (legacy name; populated on Melon/Hanteo/Circle/Line Music/Pandora/Anghami)." }, "optionalFields": { "type": "object", "properties": { "overallRank": { "type": [ "number", "null" ], "format": "float", "description": "Overall ranking across the platform (legacy field)." }, "videos": { "type": [ "number", "null" ], "format": "float", "description": "Number of videos contributing to the row." }, "totalVideos": { "type": [ "number", "null" ], "format": "float", "description": "Total videos across the entity." }, "metricValue": { "type": [ "number", "null" ], "format": "float", "description": "Primary metric value driving the chart position." }, "metricDiff": { "type": [ "number", "null" ], "format": "float", "description": "Change in `metricValue` vs the previous period." }, "avgPosition": { "type": [ "number", "null" ], "format": "float", "description": "Average position over the chart window." }, "score": { "type": [ "number", "null" ], "format": "float", "description": "Score driving the chart position." }, "totalFollowers": { "type": [ "number", "null" ], "format": "float", "description": "Total followers across the entity." }, "velocity": { "type": [ "number", "null" ], "format": "float", "description": "Rank-velocity signal (positive = climbing)." }, "isComeback": { "type": [ "boolean", "null" ], "description": "True when the entity re-entered the chart after a break (comeback)." }, "plays": { "type": [ "number", "null" ], "format": "float", "description": "Play count contribution." }, "playsWeekly": { "type": [ "number", "null" ], "format": "float", "description": "Weekly play count." }, "counts": { "type": [ "number", "null" ], "format": "float", "description": "Generic count metric." }, "index": { "type": [ "number", "null" ], "format": "float", "description": "Generic chart index value." }, "comments": { "type": [ "number", "null" ], "format": "float", "description": "Comment count." }, "artistName": { "type": [ "string", "null" ], "description": "Primary artist name (legacy field)." }, "label": { "type": [ "string", "null" ], "description": "Album label (Hanteo physical-record charts)." }, "physicalRecordIndex": { "type": [ "string", "null" ], "description": "Hanteo physical-record index value." }, "albumName": { "type": [ "string", "null" ], "description": "Album name (legacy field)." }, "name": { "type": [ "string", "null" ], "description": "Entity name passthrough." }, "imageUrl": { "type": [ "string", "null" ], "description": "Image URL passthrough." }, "id": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Platform identifier (legacy passthrough)." }, "platformId": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Platform-specific external identifier." } }, "description": "Per-chart optional metrics (used by the new SoundCloud chart and the hydrated TS row type)." }, "targetExtras": { "type": "object", "properties": { "airplayStreams": { "type": [ "number", "null" ], "format": "float", "description": "Airplay stream count snapshot." }, "amazonEdPlaylistCount": { "type": [ "number", "null" ], "format": "float", "description": "Number of Amazon editorial playlists containing the track." }, "amazonPlaylistCount": { "type": [ "number", "null" ], "format": "float", "description": "Number of Amazon playlists containing the track." }, "anghamiLikes": { "type": [ "number", "null" ], "format": "float", "description": "Anghami like count." }, "anghamiPlays": { "type": [ "number", "null" ], "format": "float", "description": "Anghami play count." }, "deezerEdPlaylistCount": { "type": [ "number", "null" ], "format": "float", "description": "Number of Deezer editorial playlists containing the track." }, "deezerEdPlaylistTotalReach": { "type": [ "number", "null" ], "format": "float", "description": "Total follower reach across Deezer editorial playlists." }, "deezerPlaylistCount": { "type": [ "number", "null" ], "format": "float", "description": "Number of Deezer playlists containing the track." }, "deezerPlaylistTotalReach": { "type": [ "number", "null" ], "format": "float", "description": "Total follower reach across Deezer playlists." }, "itunesEdPlaylistCount": { "type": [ "number", "null" ], "format": "float", "description": "Number of iTunes editorial playlists containing the track." }, "itunesPlaylistCount": { "type": [ "number", "null" ], "format": "float", "description": "Number of iTunes playlists containing the track." }, "lineMusicLikes": { "type": [ "number", "null" ], "format": "float", "description": "Line Music like count." }, "lineMusicListenCount": { "type": [ "number", "null" ], "format": "float", "description": "Line Music listen count." }, "melonComments": { "type": [ "number", "null" ], "format": "float", "description": "Melon comment count." }, "melonLikes": { "type": [ "number", "null" ], "format": "float", "description": "Melon like count." }, "pandoraLifetimeStationsAdded": { "type": [ "number", "null" ], "format": "float", "description": "Pandora lifetime station-additions count." }, "pandoraLifetimeStreams": { "type": [ "number", "null" ], "format": "float", "description": "Pandora lifetime stream count." }, "shazamCount": { "type": [ "number", "null" ], "format": "float", "description": "Shazam tag count." }, "siriusxmStreams": { "type": [ "number", "null" ], "format": "float", "description": "SiriusXM stream count." }, "soundcloudPlays": { "type": [ "number", "null" ], "format": "float", "description": "SoundCloud play count." }, "spotifyEdPlaylistCount": { "type": [ "number", "null" ], "format": "float", "description": "Number of Spotify editorial playlists containing the track." }, "spotifyEdPlaylistTotalReach": { "type": [ "number", "null" ], "format": "float", "description": "Total follower reach across Spotify editorial playlists." }, "spotifyPlaylistCount": { "type": [ "number", "null" ], "format": "float", "description": "Number of Spotify playlists containing the track." }, "spotifyPlaylistTotalReach": { "type": [ "number", "null" ], "format": "float", "description": "Total follower reach across Spotify playlists." }, "spotifyPlays": { "type": [ "number", "null" ], "format": "float", "description": "Spotify play count snapshot." }, "spotifyPopularity": { "type": [ "number", "null" ], "format": "float", "description": "Spotify popularity score (0–100)." }, "tiktokTopVideosComments": { "type": [ "number", "null" ], "format": "float", "description": "Comment count across the track's top TikTok videos." }, "tiktokTopVideosLikes": { "type": [ "number", "null" ], "format": "float", "description": "Like count across the track's top TikTok videos." }, "tiktokTopVideosViews": { "type": [ "number", "null" ], "format": "float", "description": "View count across the track's top TikTok videos." }, "youtubeComments": { "type": [ "number", "null" ], "format": "float", "description": "YouTube comment count." }, "youtubeEdPlaylistCount": { "type": [ "number", "null" ], "format": "float", "description": "Number of YouTube editorial playlists containing the track." }, "youtubeEdPlaylistTotalReach": { "type": [ "number", "null" ], "format": "float", "description": "Total follower reach across YouTube editorial playlists." }, "youtubeLikes": { "type": [ "number", "null" ], "format": "float", "description": "YouTube like count." }, "youtubePlaylistCount": { "type": [ "number", "null" ], "format": "float", "description": "Number of YouTube playlists containing the track." }, "youtubePlaylistTotalReach": { "type": [ "number", "null" ], "format": "float", "description": "Total follower reach across YouTube playlists." }, "youtubeViews": { "type": [ "number", "null" ], "format": "float", "description": "YouTube view count." } }, "description": "Cross-platform metric snapshots hydrated from per-target cache rows." }, "isChartGenre": { "type": [ "boolean", "null" ], "description": "True when the entity's genre matches the chart's genre filter." }, "externalId": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Platform external identifier (e.g. Hanteo internal index, SoundCloud track ID)." }, "externalUrl": { "type": [ "string", "null" ], "description": "Platform external URL." }, "isrc": { "type": [ "string", "null" ], "description": "International Standard Recording Code (SoundCloud chart only)." }, "entityGenre": { "type": [ "string", "null" ], "description": "Entity-level genre (when distinct from chart genre)." }, "id": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Numeric platform ID (Hanteo legacy field)." }, "platform_id": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Platform-side external ID (Hanteo legacy field)." } } }, "description": "List of regional chart rows." } }, "additionalProperties": false }, "examples": { "default": { "value": { "obj": [ { "entityId": 15191225, "targetId": "44638780", "country": "00", "cityId": 0, "genre": "Country", "rank": 1, "rankDiff": 0, "rankTrend": [ { "timestp": "2025-06-29", "rank": "1" } ], "peakDate": "2023-09-14", "peakRank": 1, "velocity7Day": 0, "periodsOnChart": 622, "consecutivePeriods": 622, "chartedDate": "2025-07-04", "name": "Love Story", "imageUrl": "https://i.scdn.co/image/1558776870134bc39c55fd278f2748d338eb7887", "createdAt": "2025-07-07T10:44:56.000Z", "artists": [ { "careerStage": "superstar", "code2": "US", "id": 2762, "name": "Taylor Swift", "imageUrl": "https://share.chartmetric.com/artists/299/172/11172299/11172299-profile.webp" } ], "album": { "id": 10998, "name": "Fearless", "label": "Big Machine Records", "releaseDate": "2008-01-01T00:00:00.000Z" }, "optionalRows": { "overallRank": 0, "score": 0, "isComeback": false }, "targetExtras": { "anghamiLikes": 64284, "anghamiPlays": 1788070 }, "isChartGenre": true } ] } } } } } } } } }, "/api/charts/soundcloud/track/{chartType}": { "get": { "summary": "SoundCloud Track Chart", "tags": [ "Charts" ], "operationId": "getSoundcloudTrackCharts", "description": "Return the new SoundCloud track chart entries (deprecates the legacy `/charts/soundcloud` endpoint). SoundCloud now only publishes chart data for `US` and `UK`. Rows include `isrc`, `externalId`, `optionalFields` (vs `optionalRows` on other platforms), and `entityGenre`.", "parameters": [ { "name": "chartType", "in": "path", "schema": { "type": "string", "enum": [ "top" ], "description": "SoundCloud chart type; only `top` is currently published." }, "required": true, "description": "SoundCloud chart type; only `top` is currently published.", "examples": { "default": { "value": "top" } } }, { "name": "code2", "in": "query", "schema": { "anyOf": [ { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB')." }, { "type": "string", "enum": [ "GLOBAL" ] } ], "description": "ISO 3166-1 alpha-2 country code (uppercase, e.g. 'US') or 'GLOBAL'. When omitted, the platform's default chart scope applies." }, "required": true, "description": "ISO 3166-1 alpha-2 country code (uppercase, e.g. 'US') or 'GLOBAL'. When omitted, the platform's default chart scope applies.", "examples": { "default": { "value": "US" } } }, { "name": "genre", "in": "query", "schema": { "type": "string", "maxLength": 100, "description": "Chart genre. Use `/api/charts/genres/soundcloud?code2={code2}` to retrieve available genres for a country." }, "required": true, "description": "Chart genre. Use `/api/charts/genres/soundcloud?code2={code2}` to retrieve available genres for a country.", "examples": { "default": { "value": "example" } } }, { "name": "date", "in": "query", "schema": { "anyOf": [ { "type": "string", "format": "date-time", "x-required": true } ], "description": "Date for the time-slice (YYYY-MM-DD). Required unless `latest=true`." }, "required": false, "description": "Date for the time-slice (YYYY-MM-DD). Required unless `latest=true`." }, { "name": "latest", "in": "query", "schema": { "type": "boolean", "description": "If true, use the most recently available date and ignore `date`." }, "required": false, "description": "If true, use the most recently available date and ignore `date`." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "description": "Maximum number of items to return per request.", "default": 100 }, "required": false, "description": "Maximum number of items to return per request." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, "required": false, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "entityId": { "type": [ "integer", "null" ], "description": "Internal Chartmetric entity ID." }, "targetId": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Platform-side track / album / user ID." }, "duration": { "type": [ "string", "null" ], "description": "Chart duration window (e.g. `daily`, `weekly`, `monthly`)." }, "country": { "type": [ "string", "null" ], "description": "Chart country code (ISO 3166-1 alpha-2; empty string for non-country-scoped charts)." }, "cityId": { "type": [ "integer", "null" ], "description": "Chartmetric city ID, or 0 when not city-scoped." }, "genre": { "type": [ "string", "null" ], "description": "Chart genre." }, "rank": { "type": [ "integer", "null" ], "description": "Current chart rank (1 = top)." }, "rankDiff": { "type": [ "number", "null" ], "format": "float", "description": "Rank change from the previous period (negative = climbed)." }, "rankTrend": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "timestp": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp at which the rank was recorded." }, "rank": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Rank at `timestp` (1 = top). Currently emitted as a string by the CCC pipeline." } } }, "description": "Historical rank samples for the row." }, "peakDate": { "type": [ "string", "null" ], "format": "date-time", "description": "Date the entity achieved its peak rank." }, "peakRank": { "type": [ "integer", "null" ], "description": "Best (lowest-numbered) rank achieved." }, "velocity7Day": { "type": [ "number", "null" ], "format": "float", "description": "7-day rank velocity (positive = trending up)." }, "periodsOnChart": { "type": [ "integer", "null" ], "description": "Total chart periods on the chart." }, "consecutivePeriods": { "type": [ "integer", "null" ], "description": "Consecutive chart periods without falling off." }, "chartedDate": { "type": [ "string", "null" ], "format": "date-time", "description": "Date of the chart row." }, "name": { "type": [ "string", "null" ], "description": "Entity name (track / album)." }, "imageUrl": { "type": [ "string", "null" ], "description": "Entity cover image URL." }, "createdAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Cache row creation timestamp." }, "artists": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ], "description": "Chartmetric artist ID." }, "name": { "type": [ "string", "null" ], "description": "Artist name." }, "code2": { "type": [ "string", "null" ], "description": "Artist country code (ISO 3166-1 alpha-2)." }, "careerStage": { "type": [ "string", "null" ], "description": "Artist career stage (e.g. `undiscovered`, `developing`, `mid-level`, `mainstream`, `superstar`, `legendary`)." }, "imageUrl": { "type": [ "string", "null" ], "description": "Artist image URL." } } }, "description": "Artists associated with the entity." }, "album": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "integer", "null" ], "description": "Chartmetric album ID." }, "name": { "type": [ "string", "null" ], "description": "Album name." }, "label": { "type": [ "string", "null" ], "description": "Album record label." }, "releaseDate": { "type": [ "string", "null" ], "format": "date-time", "description": "Album release date." } }, "description": "Album the entity belongs to (or the album itself for album charts)." }, "optionalRows": { "type": "object", "properties": { "overallRank": { "type": [ "number", "null" ], "format": "float", "description": "Overall ranking across the platform (legacy field)." }, "videos": { "type": [ "number", "null" ], "format": "float", "description": "Number of videos contributing to the row." }, "totalVideos": { "type": [ "number", "null" ], "format": "float", "description": "Total videos across the entity." }, "metricValue": { "type": [ "number", "null" ], "format": "float", "description": "Primary metric value driving the chart position." }, "metricDiff": { "type": [ "number", "null" ], "format": "float", "description": "Change in `metricValue` vs the previous period." }, "avgPosition": { "type": [ "number", "null" ], "format": "float", "description": "Average position over the chart window." }, "score": { "type": [ "number", "null" ], "format": "float", "description": "Score driving the chart position." }, "totalFollowers": { "type": [ "number", "null" ], "format": "float", "description": "Total followers across the entity." }, "velocity": { "type": [ "number", "null" ], "format": "float", "description": "Rank-velocity signal (positive = climbing)." }, "isComeback": { "type": [ "boolean", "null" ], "description": "True when the entity re-entered the chart after a break (comeback)." }, "plays": { "type": [ "number", "null" ], "format": "float", "description": "Play count contribution." }, "playsWeekly": { "type": [ "number", "null" ], "format": "float", "description": "Weekly play count." }, "counts": { "type": [ "number", "null" ], "format": "float", "description": "Generic count metric." }, "index": { "type": [ "number", "null" ], "format": "float", "description": "Generic chart index value." }, "comments": { "type": [ "number", "null" ], "format": "float", "description": "Comment count." }, "artistName": { "type": [ "string", "null" ], "description": "Primary artist name (legacy field)." }, "label": { "type": [ "string", "null" ], "description": "Album label (Hanteo physical-record charts)." }, "physicalRecordIndex": { "type": [ "string", "null" ], "description": "Hanteo physical-record index value." }, "albumName": { "type": [ "string", "null" ], "description": "Album name (legacy field)." }, "name": { "type": [ "string", "null" ], "description": "Entity name passthrough." }, "imageUrl": { "type": [ "string", "null" ], "description": "Image URL passthrough." }, "id": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Platform identifier (legacy passthrough)." }, "platformId": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Platform-specific external identifier." } }, "description": "Per-chart optional metrics (legacy name; populated on Melon/Hanteo/Circle/Line Music/Pandora/Anghami)." }, "optionalFields": { "type": "object", "properties": { "overallRank": { "type": [ "number", "null" ], "format": "float", "description": "Overall ranking across the platform (legacy field)." }, "videos": { "type": [ "number", "null" ], "format": "float", "description": "Number of videos contributing to the row." }, "totalVideos": { "type": [ "number", "null" ], "format": "float", "description": "Total videos across the entity." }, "metricValue": { "type": [ "number", "null" ], "format": "float", "description": "Primary metric value driving the chart position." }, "metricDiff": { "type": [ "number", "null" ], "format": "float", "description": "Change in `metricValue` vs the previous period." }, "avgPosition": { "type": [ "number", "null" ], "format": "float", "description": "Average position over the chart window." }, "score": { "type": [ "number", "null" ], "format": "float", "description": "Score driving the chart position." }, "totalFollowers": { "type": [ "number", "null" ], "format": "float", "description": "Total followers across the entity." }, "velocity": { "type": [ "number", "null" ], "format": "float", "description": "Rank-velocity signal (positive = climbing)." }, "isComeback": { "type": [ "boolean", "null" ], "description": "True when the entity re-entered the chart after a break (comeback)." }, "plays": { "type": [ "number", "null" ], "format": "float", "description": "Play count contribution." }, "playsWeekly": { "type": [ "number", "null" ], "format": "float", "description": "Weekly play count." }, "counts": { "type": [ "number", "null" ], "format": "float", "description": "Generic count metric." }, "index": { "type": [ "number", "null" ], "format": "float", "description": "Generic chart index value." }, "comments": { "type": [ "number", "null" ], "format": "float", "description": "Comment count." }, "artistName": { "type": [ "string", "null" ], "description": "Primary artist name (legacy field)." }, "label": { "type": [ "string", "null" ], "description": "Album label (Hanteo physical-record charts)." }, "physicalRecordIndex": { "type": [ "string", "null" ], "description": "Hanteo physical-record index value." }, "albumName": { "type": [ "string", "null" ], "description": "Album name (legacy field)." }, "name": { "type": [ "string", "null" ], "description": "Entity name passthrough." }, "imageUrl": { "type": [ "string", "null" ], "description": "Image URL passthrough." }, "id": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Platform identifier (legacy passthrough)." }, "platformId": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Platform-specific external identifier." } }, "description": "Per-chart optional metrics (used by the new SoundCloud chart and the hydrated TS row type)." }, "targetExtras": { "type": "object", "properties": { "airplayStreams": { "type": [ "number", "null" ], "format": "float", "description": "Airplay stream count snapshot." }, "amazonEdPlaylistCount": { "type": [ "number", "null" ], "format": "float", "description": "Number of Amazon editorial playlists containing the track." }, "amazonPlaylistCount": { "type": [ "number", "null" ], "format": "float", "description": "Number of Amazon playlists containing the track." }, "anghamiLikes": { "type": [ "number", "null" ], "format": "float", "description": "Anghami like count." }, "anghamiPlays": { "type": [ "number", "null" ], "format": "float", "description": "Anghami play count." }, "deezerEdPlaylistCount": { "type": [ "number", "null" ], "format": "float", "description": "Number of Deezer editorial playlists containing the track." }, "deezerEdPlaylistTotalReach": { "type": [ "number", "null" ], "format": "float", "description": "Total follower reach across Deezer editorial playlists." }, "deezerPlaylistCount": { "type": [ "number", "null" ], "format": "float", "description": "Number of Deezer playlists containing the track." }, "deezerPlaylistTotalReach": { "type": [ "number", "null" ], "format": "float", "description": "Total follower reach across Deezer playlists." }, "itunesEdPlaylistCount": { "type": [ "number", "null" ], "format": "float", "description": "Number of iTunes editorial playlists containing the track." }, "itunesPlaylistCount": { "type": [ "number", "null" ], "format": "float", "description": "Number of iTunes playlists containing the track." }, "lineMusicLikes": { "type": [ "number", "null" ], "format": "float", "description": "Line Music like count." }, "lineMusicListenCount": { "type": [ "number", "null" ], "format": "float", "description": "Line Music listen count." }, "melonComments": { "type": [ "number", "null" ], "format": "float", "description": "Melon comment count." }, "melonLikes": { "type": [ "number", "null" ], "format": "float", "description": "Melon like count." }, "pandoraLifetimeStationsAdded": { "type": [ "number", "null" ], "format": "float", "description": "Pandora lifetime station-additions count." }, "pandoraLifetimeStreams": { "type": [ "number", "null" ], "format": "float", "description": "Pandora lifetime stream count." }, "shazamCount": { "type": [ "number", "null" ], "format": "float", "description": "Shazam tag count." }, "siriusxmStreams": { "type": [ "number", "null" ], "format": "float", "description": "SiriusXM stream count." }, "soundcloudPlays": { "type": [ "number", "null" ], "format": "float", "description": "SoundCloud play count." }, "spotifyEdPlaylistCount": { "type": [ "number", "null" ], "format": "float", "description": "Number of Spotify editorial playlists containing the track." }, "spotifyEdPlaylistTotalReach": { "type": [ "number", "null" ], "format": "float", "description": "Total follower reach across Spotify editorial playlists." }, "spotifyPlaylistCount": { "type": [ "number", "null" ], "format": "float", "description": "Number of Spotify playlists containing the track." }, "spotifyPlaylistTotalReach": { "type": [ "number", "null" ], "format": "float", "description": "Total follower reach across Spotify playlists." }, "spotifyPlays": { "type": [ "number", "null" ], "format": "float", "description": "Spotify play count snapshot." }, "spotifyPopularity": { "type": [ "number", "null" ], "format": "float", "description": "Spotify popularity score (0–100)." }, "tiktokTopVideosComments": { "type": [ "number", "null" ], "format": "float", "description": "Comment count across the track's top TikTok videos." }, "tiktokTopVideosLikes": { "type": [ "number", "null" ], "format": "float", "description": "Like count across the track's top TikTok videos." }, "tiktokTopVideosViews": { "type": [ "number", "null" ], "format": "float", "description": "View count across the track's top TikTok videos." }, "youtubeComments": { "type": [ "number", "null" ], "format": "float", "description": "YouTube comment count." }, "youtubeEdPlaylistCount": { "type": [ "number", "null" ], "format": "float", "description": "Number of YouTube editorial playlists containing the track." }, "youtubeEdPlaylistTotalReach": { "type": [ "number", "null" ], "format": "float", "description": "Total follower reach across YouTube editorial playlists." }, "youtubeLikes": { "type": [ "number", "null" ], "format": "float", "description": "YouTube like count." }, "youtubePlaylistCount": { "type": [ "number", "null" ], "format": "float", "description": "Number of YouTube playlists containing the track." }, "youtubePlaylistTotalReach": { "type": [ "number", "null" ], "format": "float", "description": "Total follower reach across YouTube playlists." }, "youtubeViews": { "type": [ "number", "null" ], "format": "float", "description": "YouTube view count." } }, "description": "Cross-platform metric snapshots hydrated from per-target cache rows." }, "isChartGenre": { "type": [ "boolean", "null" ], "description": "True when the entity's genre matches the chart's genre filter." }, "externalId": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Platform external identifier (e.g. Hanteo internal index, SoundCloud track ID)." }, "externalUrl": { "type": [ "string", "null" ], "description": "Platform external URL." }, "isrc": { "type": [ "string", "null" ], "description": "International Standard Recording Code (SoundCloud chart only)." }, "entityGenre": { "type": [ "string", "null" ], "description": "Entity-level genre (when distinct from chart genre)." }, "id": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Numeric platform ID (Hanteo legacy field)." }, "platform_id": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Platform-side external ID (Hanteo legacy field)." } } }, "description": "List of regional chart rows." } }, "additionalProperties": false }, "examples": { "default": { "value": { "obj": [ { "entityId": 153482095, "targetId": "2176782261", "country": "US", "cityId": 0, "genre": "all music genres", "rank": 1, "rankDiff": 2, "rankTrend": [ { "timestp": "2025-11-24", "rank": "3" } ], "peakDate": "2025-10-30", "peakRank": 1, "velocity7Day": 0.2857143, "periodsOnChart": 57, "consecutivePeriods": 57, "chartedDate": "2025-11-27", "name": "What You Is", "imageUrl": "https://is1-ssl.mzstatic.com/image/thumb/Music211/v4/49/28/fc/4928fc53-b49f-5e65-45e9-404eca11726f/25UM1IM51211.rgb.jpg/160x160bb.jpg", "createdAt": "2025-11-28T07:23:15.000Z", "artists": [ { "careerStage": "superstar", "code2": "US", "id": 215373, "name": "YoungBoy Never Broke Again", "imageUrl": "https://i.scdn.co/image/ab6761610000e5eb776e469c846c205685141317" } ], "album": { "id": 47470879, "name": "What You Is - Single", "label": "Never Broke Again, LLC/Motown Records", "releaseDate": "2025-09-26T00:00:00.000Z" }, "isrc": "USUG12508898", "externalId": "2176782261", "optionalFields": { "artistName": "YoungBoy Never Broke Again", "overallRank": 0, "score": 0, "isComeback": false, "name": "What You Is", "imageUrl": "https://i1.sndcdn.com/artworks-GOzyCU2UJ0j8-0-large.jpg", "albumName": "What You Is" }, "targetExtras": { "soundcloudPlays": 500000 }, "isChartGenre": true, "entityGenre": "hip hop" } ] } } } } } } } } }, "/api/charts/{platform}/countries": { "get": { "summary": "List Chart Countries for Platform", "tags": [ "Charts" ], "operationId": "listChartCountries", "description": "Return the country codes with available chart data for the given `platform`. Query params (`chart_type`, `type`, `duration`) are needed for platforms whose chart countries vary by chart type / duration (e.g. Airplay, Amazon, Apple Music, iTunes, Spotify, TikTok, YouTube). Platforms with a single chart type (Deezer, Shazam, SoundCloud) do not need these params. The handler wraps the response in `{ obj: { countries } }` where `countries` depends on the platform — usually an array of ISO 3166-1 alpha-2 codes.", "parameters": [ { "name": "platform", "in": "path", "schema": { "type": "string", "enum": [ "airplay", "amazon", "applemusic", "deezer", "itunes", "shazam", "soundcloud", "spotify", "tiktok", "youtube" ], "description": "Chart platform (e.g. `airplay`, `amazon`, `applemusic`, `deezer`, `itunes`, `shazam`, `soundcloud`, `spotify`, `tiktok`, `youtube`)." }, "required": true, "description": "Chart platform (e.g. `airplay`, `amazon`, `applemusic`, `deezer`, `itunes`, `shazam`, `soundcloud`, `spotify`, `tiktok`, `youtube`).", "examples": { "default": { "value": "airplay" } } }, { "name": "chart_type", "in": "query", "schema": { "anyOf": [ { "type": "string", "enum": [ "tracks", "artists" ], "x-required": true }, { "type": "string", "enum": [ "tracks", "albums" ], "x-required": true }, { "type": "string", "enum": [ "albums", "tracks", "videos" ], "x-required": true }, { "type": "string", "enum": [ "tracks" ], "x-required": true }, { "type": "string", "enum": [ "artists", "tracks", "trends", "videos", "shorts" ], "x-required": true } ], "description": "Chart type within the platform. Required for platforms whose country list varies by chart type; rejected for platforms with a single chart type (e.g. Deezer, Shazam, SoundCloud)." }, "required": false, "description": "Chart type within the platform. Required for platforms whose country list varies by chart type; rejected for platforms with a single chart type (e.g. Deezer, Shazam, SoundCloud)." }, { "name": "duration", "in": "query", "schema": { "anyOf": [ { "type": "string", "enum": [ "daily", "weekly" ], "x-required": true }, { "anyOf": [ { "type": "string", "enum": [ "daily", "weekly" ], "x-required": true } ] } ], "description": "Chart duration. Required for `platform=airplay`, and for `platform=youtube` with `chart_type=shorts`. Forbidden otherwise." }, "required": false, "description": "Chart duration. Required for `platform=airplay`, and for `platform=youtube` with `chart_type=shorts`. Forbidden otherwise." }, { "name": "type", "in": "query", "schema": { "anyOf": [ { "type": "string", "enum": [ "popular_track", "new_track", "popular_album", "new_album" ], "x-required": true }, { "anyOf": [ { "type": "string", "enum": [ "top", "daily" ], "x-required": true } ] } ], "description": "Chart sub-type. Required for `platform=amazon` (`new_album`, `new_track`, `popular_album`, `popular_track`) and for `platform=applemusic` with `chart_type=tracks` (`top`, `daily`, `city`)." }, "required": false, "description": "Chart sub-type. Required for `platform=amazon` (`new_album`, `new_track`, `popular_album`, `popular_track`) and for `platform=applemusic` with `chart_type=tracks` (`top`, `daily`, `city`)." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": [ "object", "null" ], "properties": { "countries": { "anyOf": [ { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "object", "properties": {} } ] } }, { "type": "object", "properties": {} }, { "type": "string" } ], "nullable": true, "description": "Country codes available for the requested chart. Usually an array of ISO 3166-1 alpha-2 codes; some platforms emit nested maps when chart type / duration do not resolve to a single list." } } } }, "additionalProperties": false }, "examples": { "default": { "value": { "obj": { "countries": [ "US", "GB", "BR", "JP", "KR" ] } } } } } } } } } }, "/api/charts/{streamingType}/dates": { "get": { "summary": "List Chart Dates for Streaming Type", "tags": [ "Charts" ], "operationId": "listChartDates", "description": "Return the dates with available chart data for the given `streamingType`. Source varies by platform: S3, Snowflake, ClickHouse, or RDS (see `ChartFilterOptionsService.getChartDatesDataSource`). Returns an array of `{ timestp }` objects wrapped by `handleDBResponse(res, \"obj\")`.", "parameters": [ { "name": "streamingType", "in": "path", "schema": { "type": "string", "enum": [ "acr_daily_artist", "acr_weekly_artist", "acr_daily_track", "acr_weekly_track", "amazon", "amazon_albums", "amazon_new_tracks", "apple_music", "apple_music_daily", "apple_music_newcomers", "apple_music_albums", "apple_music_videos", "beatport", "deezer", "qq", "shazam", "soundcloud", "soundcloud_trending", "spotify_artist", "fresh_finds", "spotify_tracks", "tiktok", "tiktok_daily", "tiktok_weekly", "tiktok_video", "tiktok_user_likes", "tiktok_user_followers", "tiktok_weekly_user_likes", "tiktok_weekly_user_followers", "tiktok_daily_user_likes", "tiktok_daily_user_followers", "tiktok_country_weekly", "twitch_user_followers", "twitch_monthly_viewer_hours", "twitch_weekly_user_followers", "twitch_weekly_viewer_hours", "youtube_tracks", "youtube_videos", "youtube_videos_daily", "youtube_trends", "youtube_artists", "youtube_daily_shorts", "youtube_weekly_shorts", "itunes", "itunes_videos", "itunes_albums", "melon_daily", "melon_weekly", "melon_monthly", "melon_yearly", "melon", "hanteo", "line_daily", "line_weekly", "line_daily_albums", "line_weekly_albums", "pandora_top_spins", "pandora_top_thumbs", "anghami_plays", "anghami_likes", "circle" ], "description": "Streaming type whose available chart dates are returned (e.g. `spotify_track`, `spotify_artist`, `youtube`, `tiktok_top_tracks`, `melon_daily`)." }, "required": true, "description": "Streaming type whose available chart dates are returned (e.g. `spotify_track`, `spotify_artist`, `youtube`, `tiktok_top_tracks`, `melon_daily`).", "examples": { "default": { "value": "acr_daily_artist" } } }, { "name": "fromDaysAgo", "in": "query", "schema": { "type": "integer", "description": "Look-back window in days; e.g. `fromDaysAgo=9999` returns all available chart dates." }, "required": true, "description": "Look-back window in days; e.g. `fromDaysAgo=9999` returns all available chart dates.", "examples": { "default": { "value": 1 } } }, { "name": "chartEntity", "in": "query", "schema": { "type": "string", "enum": [ "track", "album", "artist", "video" ], "description": "Chart entity (`track` or `album`). Required only for chart types that vary by entity." }, "required": false, "description": "Chart entity (`track` or `album`). Required only for chart types that vary by entity." }, { "name": "chartType", "in": "query", "schema": { "type": "string", "description": "Chart type within the streaming platform. Required only for some charts; see each chart endpoint for the valid values." }, "required": false, "description": "Chart type within the streaming platform. Required only for some charts; see each chart endpoint for the valid values." }, { "name": "duration", "in": "query", "schema": { "type": "string", "enum": [ "daily", "weekly", "monthly", "semi-yearly", "yearly", "all_time" ], "description": "Chart duration (e.g. `daily`, `weekly`, `monthly`, `all_time`). Required only for some charts." }, "required": false, "description": "Chart duration (e.g. `daily`, `weekly`, `monthly`, `all_time`). Required only for some charts." }, { "name": "country", "in": "query", "schema": { "type": "string", "description": "Country code (ISO 3166-1 alpha-2). Required only for some charts." }, "required": false, "description": "Country code (ISO 3166-1 alpha-2). Required only for some charts." }, { "name": "genre", "in": "query", "schema": { "type": "string", "description": "Chart genre. Required only for some charts." }, "required": false, "description": "Chart genre. Required only for some charts." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "timestp": { "type": [ "string", "null" ], "format": "date-time", "description": "Available chart date for the streaming type." } } }, "description": "List of chart dates available for the requested streaming type." } }, "additionalProperties": false }, "examples": { "default": { "value": { "obj": [ { "timestp": "2025-04-23T07:00:00.000Z" }, { "timestp": "2025-04-13T07:00:00.000Z" }, { "timestp": "2025-04-06T07:00:00.000Z" }, { "timestp": "2025-03-30T07:00:00.000Z" } ] } } } } } } } } }, "/api/charts/genres/{platform}": { "get": { "summary": "List Chart Genres for Platform", "tags": [ "Charts" ], "operationId": "listChartGenres", "description": "Return the available chart genres for the given `platform` (optionally filtered by `code2`). Shape is highly platform-dependent — Amazon returns `[{ id, name }]`, Apple Music / iTunes / Beatport return hardcoded string arrays, SoundCloud / Anghami / Siriusxm return DB-backed string arrays, and Melon / Tencent return DB-backed object arrays. The envelope `{ obj: [...] }` is always a list but the element type varies per platform.", "parameters": [ { "name": "platform", "in": "path", "schema": { "type": "string", "enum": [ "amazon", "amazon_albums", "apple_music", "apple_music_albums", "apple_music_videos", "beatport", "itunes", "itunes_albums", "itunes_videos", "line_daily", "melon_daily", "melon_monthly", "melon_weekly", "melon_yearly", "shazam_genre", "soundcloud", "soundcloud_legacy", "soundcloud_trending", "siriusxm", "tencent_weekly", "tencent_monthly", "anghami", "genius" ], "description": "Chart platform whose genre list is returned (e.g. `amazon`, `applemusic`, `itunes`, `soundcloud`, `melon`)." }, "required": true, "description": "Chart platform whose genre list is returned (e.g. `amazon`, `applemusic`, `itunes`, `soundcloud`, `melon`).", "examples": { "default": { "value": "amazon" } } }, { "name": "code2", "in": "query", "schema": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB').", "default": "US" }, "required": false, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB')." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": [ "array", "null" ], "items": { "anyOf": [ { "type": "string" }, { "type": "object", "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Genre ID (Amazon, Melon, Tencent)." }, "name": { "type": [ "string", "null" ], "description": "Genre name." } } } ] }, "description": "List of available chart genres. Element is a string on most platforms; `{ id, name }` object on Amazon / Melon / Tencent." } }, "additionalProperties": false }, "examples": { "default": { "value": { "obj": [ "all music genres", "artist pro", "dance", "folk", "hip hop", "indie", "new & hot", "next pro", "pop", "r&b", "rock" ] } } } } } } } } }, "/api/city/{id}/{domain}/top-artists": { "get": { "summary": "List Top Artists in a City", "tags": [ "City" ], "operationId": "listCityTopArtists", "description": "Top artists in a city for a given platform (`domain` in `spotify | youtube | shazam | radio | instagram`). Each item merges per-platform stats (`count`, and `username` when `domain=instagram`) with basic artist info (IDs, audience stats, genre tags, latest release). `count` is surfaced as a string when the underlying aggregate returns a `BIGINT`.", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric city ID." }, "required": true, "description": "Chartmetric city ID.", "examples": { "default": { "value": 1 } } }, { "name": "domain", "in": "path", "schema": { "type": "string", "enum": [ "spotify", "youtube", "shazam", "radio", "instagram" ], "description": "Platform whose audience signal ranks the artists (one of `spotify | youtube | shazam | radio | instagram`)." }, "required": true, "description": "Platform whose audience signal ranks the artists (one of `spotify | youtube | shazam | radio | instagram`).", "examples": { "default": { "value": "spotify" } } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "array", "items": { "type": "object", "properties": { "count": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "nullable": true, "description": "Local audience signal: `spotify` → monthly listeners; `youtube` → daily views; `instagram` → followers; `shazam`/`radio` → occurrences. May arrive as a string when the aggregate is `BIGINT`." }, "username": { "type": [ "string", "null" ], "description": "Instagram username of the artist; only populated when `domain=instagram`." }, "id": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric artist ID." }, "name": { "type": [ "string", "null" ], "description": "Artist display name." }, "image_url": { "type": [ "string", "null" ], "description": "URL of the artist profile image." }, "isni": { "type": [ "string", "null" ], "description": "International Standard Name Identifier (ISNI) of the artist." }, "code2": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-2 country code of the artist's primary country (2 letters, e.g. 'us', 'br')." }, "hometown_city": { "type": [ "string", "null" ], "description": "Artist's hometown city." }, "current_city": { "type": [ "string", "null" ], "description": "Artist's current city." }, "verified": { "type": [ "boolean", "null" ], "description": "Whether the artist is verified on the underlying platform." }, "band": { "type": [ "boolean", "null" ], "description": "True when the artist is a band/group rather than a solo act." }, "gender": { "type": [ "string", "null" ], "description": "Artist gender label (e.g. 'male', 'female', 'mixed', 'non-binary')." }, "sp_followers": { "type": [ "integer", "null" ], "description": "Spotify follower count." }, "sp_popularity": { "type": [ "integer", "null" ], "description": "Spotify popularity score (0–100)." }, "sp_monthly_listeners": { "type": [ "integer", "null" ], "description": "Spotify monthly listeners." }, "deezer_fans": { "type": [ "integer", "null" ], "description": "Deezer fan count." }, "cm_artist_rank": { "type": [ "integer", "null" ], "description": "Global Chartmetric artist rank (1 is highest)." }, "cm_artist_score": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric artist score (0–100)." }, "primary_genre_smart": { "anyOf": [ { "type": "integer" }, { "type": "string" }, { "type": "object", "properties": {} } ], "nullable": true, "description": "Primary genre under Chartmetric's smart-genre taxonomy; surfaced as an ID, a name, or a `{id, name}` object depending on the join." }, "tags": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Genre tags associated with the artist." }, "spotify_artist_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Spotify artist IDs linked to this Chartmetric artist." }, "itunes_artist_ids": { "type": [ "array", "null" ], "items": { "type": [ "integer", "null" ] }, "description": "iTunes/Apple Music artist IDs linked to this Chartmetric artist." }, "deezer_artist_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Deezer artist IDs linked to this Chartmetric artist." }, "amazon_artist_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Amazon Music artist IDs linked to this Chartmetric artist." }, "latest_release": { "type": [ "object", "null" ], "properties": { "cm_album": { "type": [ "integer", "null" ], "description": "Chartmetric album ID of the most recent release." }, "album_name": { "type": [ "string", "null" ], "description": "Album title." }, "release_date": { "type": [ "string", "null" ], "format": "date-time", "description": "Album release date (ISO 8601)." }, "upc": { "type": [ "string", "null" ], "description": "Universal Product Code identifying the release." }, "label": { "type": [ "string", "null" ], "description": "Record label that released the album." }, "image_url": { "type": [ "string", "null" ], "description": "URL of the album cover image." } }, "description": "Most recent album release attributed to this artist; `null` when the artist has no release on file." } }, "required": [ "id" ] } } }, "required": [ "obj" ], "additionalProperties": false }, "examples": { "default": { "value": { "obj": [ { "count": "258", "id": 1401297, "name": "Pop Smoke", "image_url": "https://i.scdn.co/image/8f0a45ff4868c7868a7996b57da64f2e89042e26", "isni": null, "code2": "us", "hometown_city": null, "current_city": null, "verified": false, "band": false, "gender": null, "sp_followers": 1374300, "sp_popularity": 95, "sp_monthly_listeners": 27687238, "deezer_fans": 181349, "cm_artist_rank": 37, "cm_artist_score": 92.4, "primary_genre_smart": 501121, "tags": [ "rap" ], "spotify_artist_ids": [ "0eDvMgVFoNV3TpwtrVCoTj" ], "itunes_artist_ids": [ 1450601383 ], "deezer_artist_ids": [ "58447102" ], "amazon_artist_ids": [ "B07N6R3268" ], "latest_release": { "cm_album": 6591557, "album_name": "今は亡きあの人たち", "release_date": "2020-08-19T07:00:00.000Z", "upc": "602435142609", "label": "UMG Recordings, Inc.", "image_url": "https://i.scdn.co/image/ab67616d0000b27349066d2258ad2e46955e2381" } } ] } } } } } } } } }, "/api/city/{id}/{domain}/top-tracks": { "get": { "summary": "List Top Tracks in a City", "tags": [ "City" ], "operationId": "listCityTopTracks", "description": "Top tracks in a city for a given platform (`domain` in `youtube | shazam | radio`). Each item merges per-platform stats with basic track metadata (cm_track, artists, album info, genre tags). `position_stats` is only populated when `domain=shazam`. `count` is surfaced as a string when the underlying aggregate returns a `BIGINT`.", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric city ID." }, "required": true, "description": "Chartmetric city ID.", "examples": { "default": { "value": 1 } } }, { "name": "domain", "in": "path", "schema": { "type": "string", "enum": [ "youtube", "radio", "shazam" ], "description": "Platform whose audience signal ranks the tracks (one of `youtube | shazam | radio`)." }, "required": true, "description": "Platform whose audience signal ranks the tracks (one of `youtube | shazam | radio`).", "examples": { "default": { "value": "youtube" } } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "array", "items": { "type": "object", "properties": { "isrc": { "type": "string", "description": "International Standard Recording Code identifying the track." }, "count": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "nullable": true, "description": "Local audience signal in this city for the requested `domain`: YouTube daily views or Shazam/radio occurrences. Returned as a string when the underlying aggregate is `BIGINT`." }, "position_stats": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "timestp": { "anyOf": [ { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Timestamp of the chart sample." }, "position": { "type": [ "integer", "null" ], "description": "Track position on the chart at this timestamp (1 is highest)." } } }, "description": "Chart position history for this track in the city; only populated when `domain=shazam`." }, "id": { "type": [ "integer", "null" ], "description": "Chartmetric track ID. Same value as `cm_track`." }, "name": { "type": [ "string", "null" ], "description": "Track title." }, "image_url": { "type": [ "string", "null" ], "description": "URL of the track artwork." }, "description": { "type": [ "string", "null" ], "description": "Free-form description for the track, when available." }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Timestamp the track was first ingested into Chartmetric (ISO 8601)." }, "modified_at": { "anyOf": [ { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Timestamp the track metadata was last updated (ISO 8601)." }, "tags": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "nullable": true, "description": "Genre tags for the track; either a comma-separated string or an array of tag strings depending on the upstream payload." }, "cm_track": { "type": [ "integer", "null" ], "description": "Chartmetric track ID." }, "cm_artist": { "type": [ "array", "null" ], "items": { "type": "integer" }, "description": "Chartmetric artist IDs credited on this track." }, "artist_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Display names of the credited artists, aligned with `cm_artist`." }, "code2s": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "ISO 3166-1 alpha-2 country codes of the credited artists, aligned with `cm_artist`." }, "artist_images": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Profile image URLs of the credited artists, aligned with `cm_artist`." }, "artist_covers": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Cover/banner image URLs of the credited artists, aligned with `cm_artist`." }, "artists": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ], "description": "Chartmetric artist ID." }, "name": { "type": [ "string", "null" ], "description": "Artist display name." } } }, "description": "Credited artists as `{id, name}` objects; equivalent to zipping `cm_artist` with `artist_names`." }, "spotify_track_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Spotify track IDs linked to this Chartmetric track." }, "spotify_album_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Spotify album IDs the track appears on." }, "spotify_duration_ms": { "type": [ "integer", "null" ], "description": "Track duration on Spotify in milliseconds." }, "itunes_track_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "iTunes/Apple Music track IDs linked to this Chartmetric track." }, "itunes_album_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "iTunes/Apple Music album IDs the track appears on." }, "storefronts": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "ISO 3166-1 alpha-2 country codes of Apple Music storefronts where the iTunes IDs are valid." }, "deezer_track_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Deezer track IDs linked to this Chartmetric track." }, "deezer_album_ids": { "type": [ "array", "null" ], "items": { "type": [ "integer", "null" ] }, "description": "Deezer album IDs the track appears on." }, "deezer_duration": { "type": [ "integer", "null" ], "description": "Track duration on Deezer in seconds." }, "amazon_track_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Amazon Music track IDs linked to this Chartmetric track." }, "amazon_album_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Amazon Music album IDs the track appears on." }, "album_ids": { "type": [ "array", "null" ], "items": { "type": [ "integer", "null" ] }, "description": "Chartmetric album IDs the track appears on." }, "album_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Album titles aligned with `album_ids`." }, "album_upc": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Universal Product Codes of the albums the track appears on." }, "album_label": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Record labels of the albums the track appears on." }, "release_dates": { "type": [ "array", "null" ], "items": { "anyOf": [ { "type": "string", "format": "date-time" } ], "nullable": true }, "description": "Release dates of the albums the track appears on (ISO 8601), aligned with `album_ids`." } }, "required": [ "isrc" ] } } }, "required": [ "obj" ], "additionalProperties": false }, "examples": { "default": { "value": { "obj": [ { "isrc": "DEA629252500", "count": "28", "position_stats": [ { "timestp": "2020-08-03", "position": 81 }, { "timestp": "2020-08-04", "position": 58 } ], "id": 11291890, "name": "Major Tom", "image_url": "https://i.scdn.co/image/73b7f1f27769379d6796ed9300bda12d9dd3e75d", "description": null, "created_at": null, "modified_at": "2020-07-03T05:29:55.573Z", "tags": "Pop,Soundtrack,Soundtrack,Music,Pop", "cm_track": 11291890, "cm_artist": [ 217598 ], "artist_names": [ "Peter Schilling" ], "code2s": [ "DE" ], "artist_images": [ "https://i.scdn.co/image/3f6870676468c6f14dff7df4a7a0cc57c604e258" ], "artist_covers": [ null ], "artists": [ { "id": 217598, "name": "Peter Schilling" } ], "spotify_track_ids": [ "6lXKNdOsnaLv9LwulZbxNl" ], "spotify_album_ids": [ "1rYXSHYaxxQ9HclnAeVhxv" ], "spotify_duration_ms": 300266, "itunes_track_ids": [ "40633230" ], "itunes_album_ids": [ "40633214" ], "storefronts": [ "US" ], "deezer_track_ids": [ "520450102" ], "deezer_album_ids": [ 67074482 ], "deezer_duration": 299, "amazon_track_ids": null, "amazon_album_ids": null, "album_ids": [ 473527 ], "album_names": [ "SWR1 - Achtzig 80er" ], "album_upc": [ "5099969886652" ], "album_label": [ "EMM" ], "release_dates": [ "2009-06-19T07:00:00.000Z" ] } ] } } } } } } } } }, "/api/country/{code2}/artist-rankings/{area}/{type}/{subArea}": { "get": { "summary": "List Artist Rankings by Country", "tags": [ "Country" ], "operationId": "listCountryArtistRankings", "description": "Artist rankings within a country, filtered by `area` (`local` | `foreign`), `type` (`charts` | `audience` | `growth`) and `subArea` (`local` | `global`). The combination `foreign-*-global` is not supported and returns 400. The combination `local-audience-global` uses fan-base rank via Elasticsearch and returns a reduced field set without `local_rank_trend`. `local_rank_trend` is populated for `type=audience` rankings, except the `local-audience-global` combination.", "parameters": [ { "name": "code2", "in": "path", "schema": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB')." }, "required": true, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB').", "examples": { "default": { "value": "US" } } }, { "name": "area", "in": "path", "schema": { "type": "string", "enum": [ "local", "foreign" ], "description": "Whether to rank artists native to the country (`local`) or from outside it (`foreign`). One of `local`, `foreign`." }, "required": true, "description": "Whether to rank artists native to the country (`local`) or from outside it (`foreign`). One of `local`, `foreign`.", "examples": { "default": { "value": "local" } } }, { "name": "type", "in": "path", "schema": { "type": "string", "enum": [ "charts", "audience", "growth" ], "description": "Ranking criterion: `charts` (chart performance), `audience` (audience size), or `growth` (trending growth)." }, "required": true, "description": "Ranking criterion: `charts` (chart performance), `audience` (audience size), or `growth` (trending growth).", "examples": { "default": { "value": "charts" } } }, { "name": "subArea", "in": "path", "schema": { "anyOf": [ { "type": "string", "enum": [ "local" ], "x-required": true }, { "type": "string", "enum": [ "local", "global" ], "x-required": true } ], "description": "Ranking scope: `local` (within the country) or `global` (worldwide). When `area=foreign`, only `local` is allowed; the `foreign-*-global` combination returns 400." }, "required": true, "description": "Ranking scope: `local` (within the country) or `global` (worldwide). When `area=foreign`, only `local` is allowed; the `foreign-*-global` combination returns 400.", "examples": { "default": { "value": "local" } } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "description": "Maximum number of items to return per request.", "default": 10 }, "required": false, "description": "Maximum number of items to return per request." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, "required": false, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric artist ID." }, "name": { "type": [ "string", "null" ], "description": "Artist name." }, "image_url": { "type": [ "string", "null" ], "description": "Artist image URL." }, "isni": { "type": [ "string", "null" ], "description": "International Standard Name Identifier (ISNI) of the artist." }, "code2": { "type": [ "string", "null" ], "description": "Artist's home country (ISO 3166-1 alpha-2 code)." }, "hometown_city": { "type": [ "string", "null" ], "description": "Artist's hometown city." }, "current_city": { "type": [ "string", "null" ], "description": "Artist's current city." }, "verified": { "type": [ "boolean", "null" ], "description": "Whether the artist is verified on Spotify." }, "band": { "type": [ "boolean", "null" ], "description": "Whether the artist is a band/group rather than a solo artist." }, "gender": { "type": [ "string", "null" ], "description": "Artist gender (e.g. `male`, `female`)." }, "sp_followers": { "type": [ "integer", "null" ], "description": "Spotify follower count." }, "sp_popularity": { "type": [ "integer", "null" ], "description": "Spotify popularity score (0–100)." }, "sp_monthly_listeners": { "type": [ "integer", "null" ], "description": "Spotify monthly listener count." }, "deezer_fans": { "type": [ "integer", "null" ], "description": "Deezer fan count." }, "cm_artist_rank": { "type": [ "integer", "null" ], "description": "Global Chartmetric artist rank." }, "cm_artist_score": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric artist score (0–100), aligned with `cm_artist_rank`." }, "primary_genre_smart": { "anyOf": [ { "type": "integer" }, { "type": "string" }, { "type": "object", "properties": {} } ], "nullable": true, "description": "Primary smart genre ID (integer) for the artist; legacy shapes may surface as a string or object." }, "tags": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Genre tags associated with the artist (e.g. `country pop`, `indie rock`)." }, "spotify_artist_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Spotify artist IDs linked to this Chartmetric artist." }, "itunes_artist_ids": { "type": [ "array", "null" ], "items": { "type": "integer" }, "description": "iTunes artist IDs linked to this Chartmetric artist." }, "deezer_artist_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Deezer artist IDs linked to this Chartmetric artist." }, "amazon_artist_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Amazon Music artist IDs linked to this Chartmetric artist." }, "local_rank": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Position within the requested ranking (1-based)." }, "local_rank_trend": { "type": "array", "items": { "type": "object", "properties": {} }, "description": "Recent rank-trend snapshots. Populated for `type=audience` rankings, except the `local-audience-global` combination which omits trends." } }, "required": [ "id", "local_rank" ] } } }, "required": [ "obj" ], "additionalProperties": false }, "examples": { "default": { "value": { "obj": [ { "id": 1093307, "name": "Ella Langley", "image_url": "https://i.scdn.co/image/ab6761610000e5ebc4670378a4188c3174ef2ca9", "isni": null, "code2": "US", "hometown_city": null, "current_city": null, "verified": true, "band": false, "gender": null, "sp_followers": 1321282, "sp_popularity": 86, "sp_monthly_listeners": 24925655, "deezer_fans": 14464, "cm_artist_rank": 121, "cm_artist_score": 96.39, "primary_genre_smart": 501131, "tags": [ "country", "us country" ], "spotify_artist_ids": [ "6BRxQ8cD3eqnrVj6WKDok8" ], "itunes_artist_ids": [ 1384373733 ], "deezer_artist_ids": [ "14867123" ], "amazon_artist_ids": [ "B07D3JZFW9" ], "local_rank": 1 }, { "id": 212715, "name": "Morgan Wallen", "image_url": "https://i.scdn.co/image/ab6761610000e5eb47de0bbc22f08b5ebe14bd6e", "isni": "0000000467316966", "code2": "US", "hometown_city": "Knoxville", "current_city": "Nashville", "verified": false, "band": false, "gender": "male", "sp_followers": 15244094, "sp_popularity": 90, "sp_monthly_listeners": 33085833, "deezer_fans": 280609, "cm_artist_rank": 115, "cm_artist_score": 96.46, "primary_genre_smart": 504354, "tags": [ "country pop", "new country", "country rock", "us country", "us pop" ], "spotify_artist_ids": [ "4oUHIQIBe0LHzYfvXNW4QM" ], "itunes_artist_ids": [ 829142092 ], "deezer_artist_ids": [ "7188840" ], "amazon_artist_ids": [ "B00QNXU7TW" ], "local_rank": 2 } ] } } } } } } } } }, "/api/curator/deezer/lists": { "get": { "summary": "List Deezer Curators", "tags": [ "Curator" ], "operationId": "listCuratorsDeezer", "description": "List curators by platform. Sort columns vary by platform: `spotify` — `num_playlists` (default), `followers`, `num_updates`, `num_tracks_updated`, `fdiff_month`, `fdiff_percent_month`, `sp_playlist_total_reach`; `applemusic`/`itunes` — `num_playlists` (default); `deezer` — `num_playlists`, `total_reach` (default); `youtube` — `total_playlist_views` (default), `num_playlists`, `channel_views`, `channel_subscribers`; `amazon` — `total_playlists` (default).", "parameters": [ { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate. `offset + limit` must be ≤ 10,000 (Elasticsearch window)." }, "required": false, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate. `offset + limit` must be ≤ 10,000 (Elasticsearch window)." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 0, "description": "Maximum number of curators to return per request. Defaults to 50; max 10000. `offset + limit` must be ≤ 10,000.", "default": 50 }, "required": false, "description": "Maximum number of curators to return per request. Defaults to 50; max 10000. `offset + limit` must be ≤ 10,000." }, { "name": "sortColumn", "in": "query", "schema": { "type": "string", "enum": [ "num_playlists", "total_reach" ], "description": "Column to sort curators by. Allowed values vary per platform; see the endpoint description for the list. Default also varies per platform.", "default": "total_reach" }, "required": false, "description": "Column to sort curators by. Allowed values vary per platform; see the endpoint description for the list. Default also varies per platform." }, { "name": "sortOrderDesc", "in": "query", "schema": { "type": "boolean", "description": "If true, sort `sortColumn` in descending order. Defaults to true.", "default": true }, "required": false, "description": "If true, sort `sortColumn` in descending order. Defaults to true." }, { "name": "userListIds[]", "in": "query", "schema": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "uniqueItems": true, "description": "Filter by Chartmetric shortlist (user list) IDs the curator is included on. Public API exposes this as `shortlistIds`." }, "required": false, "description": "Filter by Chartmetric shortlist (user list) IDs the curator is included on. Public API exposes this as `shortlistIds`." }, { "name": "nameSearch", "in": "query", "schema": { "type": "string", "description": "Substring match against curator name." }, "required": false, "description": "Substring match against curator name." }, { "name": "playlistKeywordSearch", "in": "query", "schema": { "type": "string", "description": "Substring match against names of playlists owned by the curator." }, "required": false, "description": "Substring match against names of playlists owned by the curator." }, { "name": "code2", "in": "query", "schema": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB')." }, "required": false, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB')." }, { "name": "editorial", "in": "query", "schema": { "type": "boolean", "description": "If true, return only official platform editorial curators. If false, exclude them. Applies to `spotify`, `applemusic`, `amazon`, and `youtube`." }, "required": false, "description": "If true, return only official platform editorial curators. If false, exclude them. Applies to `spotify`, `applemusic`, `amazon`, and `youtube`." }, { "name": "majorLabel", "in": "query", "schema": { "type": "boolean", "description": "If true, return only major-label curators (Sony, Universal, Warner). If false, exclude them. Applies to `spotify` and `youtube`." }, "required": false, "description": "If true, return only major-label curators (Sony, Universal, Warner). If false, exclude them. Applies to `spotify` and `youtube`." }, { "name": "brand", "in": "query", "schema": { "type": "boolean", "description": "If true, return only curators associated with a brand. If false, exclude them. Applies to `spotify` and `youtube`." }, "required": false, "description": "If true, return only curators associated with a brand. If false, exclude them. Applies to `spotify` and `youtube`." }, { "name": "popularIndie", "in": "query", "schema": { "type": "boolean", "description": "If true, return only popular indie curators (not editorial/brand/major-label, with 100K+ reached followers). If false, exclude them. Applies to `spotify` and `youtube`." }, "required": false, "description": "If true, return only popular indie curators (not editorial/brand/major-label, with 100K+ reached followers). If false, exclude them. Applies to `spotify` and `youtube`." }, { "name": "indie", "in": "query", "schema": { "type": "boolean", "description": "If true, include curators that are not major-label, editorial, brand, or popular indie. If false, exclude them. Applies to `spotify`, `applemusic`, and `youtube`." }, "required": false, "description": "If true, include curators that are not major-label, editorial, brand, or popular indie. If false, exclude them. Applies to `spotify`, `applemusic`, and `youtube`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "array", "items": { "type": "object", "properties": { "position": { "type": [ "integer", "null" ], "description": "1-based rank of the curator within the entire sorted result set (i.e. `index + 1 + offset`)." }, "owner_id": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "string" } ], "description": "Chartmetric curator ID. Numeric for `spotify`, `applemusic`, `itunes`, `deezer`, `amazon`; string for `youtube` (channel ID)." }, "owner_name": { "type": [ "string", "null" ], "description": "Curator display name." }, "url": { "type": [ "string", "null" ], "description": "Image or profile URL for the curator on the platform." }, "code2": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-2 country code associated with the curator (lowercase, e.g. 'us', 'gb'). Populated for `applemusic`, `itunes`, `deezer`, `youtube`." }, "tags": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Genre tags associated with the curator." }, "num_playlists": { "type": [ "integer", "null" ], "description": "Count of the curator's playlists tracked by Chartmetric." }, "user_id": { "type": [ "string", "null" ], "description": "Platform-side user ID (Spotify user)." }, "sp_playlist_total_reach": { "type": [ "integer", "null" ], "description": "Sum of followers across all of this Spotify curator's playlists (total playlist reach). Spotify only." }, "followers": { "type": [ "integer", "null" ], "description": "Curator's follower count on the platform." }, "fdiff_month": { "type": [ "integer", "null" ], "description": "Net change in followers vs. 28 days ago. Spotify only." }, "fdiff_percent_month": { "type": [ "number", "null" ], "format": "float", "description": "Percentage change in followers vs. 28 days ago, expressed as a fraction (e.g. 0.0139 = +1.39%). Spotify only." }, "num_updates": { "type": [ "integer", "null" ], "description": "Number of updates the curator has made across their playlists. Spotify only." }, "num_tracks_updated": { "type": [ "integer", "null" ], "description": "Number of tracks added/removed across the curator's recent playlist updates. Spotify only." }, "editorial": { "type": [ "boolean", "null" ], "description": "True if this is an official platform editorial curator." }, "major_label": { "type": [ "boolean", "null" ], "description": "True if the curator is operated by a major label (Sony, Universal, Warner)." }, "brand": { "type": [ "boolean", "null" ], "description": "True if the curator is operated by a brand." }, "popular_indie": { "type": [ "boolean", "null" ], "description": "True if the curator is a popular indie (not editorial/brand/major-label, with 100K+ reached followers)." }, "indie": { "type": [ "boolean", "null" ], "description": "True if the curator is independent (not editorial, brand, major-label, or popular indie)." }, "audiobook": { "type": [ "boolean", "null" ], "description": "True if the curator focuses on audiobook content." }, "suspicion_score": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric suspicion score flagging potentially inauthentic activity (lower is cleaner). Spotify only." }, "total_reach": { "type": [ "integer", "null" ], "description": "Sum of followers across all of this curator's Deezer playlists. Deezer only." }, "total_playlists": { "type": [ "integer", "null" ], "description": "Total number of playlists owned by this curator on Amazon Music. Amazon only." }, "curator_id": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "string" } ], "nullable": true, "description": "Platform-side curator ID on Apple Music / iTunes." }, "channel_views": { "type": [ "integer", "null" ], "description": "Cumulative views across the curator's YouTube channel. YouTube only." }, "channel_subscribers": { "type": [ "integer", "null" ], "description": "Subscriber count for the curator's YouTube channel. YouTube only." }, "total_playlist_views": { "type": [ "integer", "null" ], "description": "Sum of views across all of the curator's YouTube playlists. YouTube only." } } }, "description": "List of curator entries for the requested platform." }, "offset": { "type": [ "integer", "null" ], "description": "Offset of this result page (echoes the `offset` request param)." }, "total": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "nullable": true, "description": "Total number of curators matching the filters across all pages." } }, "required": [ "obj" ] }, "examples": { "default": { "value": { "obj": [ { "position": 1, "total_reach": 25973829, "owner_id": 637006841, "url": "https://api.deezer.com/user/637006841/image", "owner_name": "Deezer Charts", "code2": "gb", "num_playlists": 66, "tags": [ "'Hip-Hop/Rap'", "'Latin'", "'Pop'" ] } ], "offset": 0, "total": 100 } } } } } } } } }, "/api/curator/itunes/lists": { "get": { "summary": "List iTunes Curators", "tags": [ "Curator" ], "operationId": "listCuratorsItunes", "description": "List curators by platform. Sort columns vary by platform: `spotify` — `num_playlists` (default), `followers`, `num_updates`, `num_tracks_updated`, `fdiff_month`, `fdiff_percent_month`, `sp_playlist_total_reach`; `applemusic`/`itunes` — `num_playlists` (default); `deezer` — `num_playlists`, `total_reach` (default); `youtube` — `total_playlist_views` (default), `num_playlists`, `channel_views`, `channel_subscribers`; `amazon` — `total_playlists` (default). Note: `itunes` and `applemusic` return the same data.", "parameters": [ { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate. `offset + limit` must be ≤ 10,000 (Elasticsearch window)." }, "required": false, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate. `offset + limit` must be ≤ 10,000 (Elasticsearch window)." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 0, "description": "Maximum number of curators to return per request. Defaults to 50; max 10000. `offset + limit` must be ≤ 10,000.", "default": 50 }, "required": false, "description": "Maximum number of curators to return per request. Defaults to 50; max 10000. `offset + limit` must be ≤ 10,000." }, { "name": "sortColumn", "in": "query", "schema": { "type": "string", "enum": [ "num_playlists" ], "description": "Column to sort curators by. Allowed values vary per platform; see the endpoint description for the list. Default also varies per platform.", "default": "num_playlists" }, "required": false, "description": "Column to sort curators by. Allowed values vary per platform; see the endpoint description for the list. Default also varies per platform." }, { "name": "sortOrderDesc", "in": "query", "schema": { "type": "boolean", "description": "If true, sort `sortColumn` in descending order. Defaults to true.", "default": true }, "required": false, "description": "If true, sort `sortColumn` in descending order. Defaults to true." }, { "name": "userListIds[]", "in": "query", "schema": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "uniqueItems": true, "description": "Filter by Chartmetric shortlist (user list) IDs the curator is included on. Public API exposes this as `shortlistIds`." }, "required": false, "description": "Filter by Chartmetric shortlist (user list) IDs the curator is included on. Public API exposes this as `shortlistIds`." }, { "name": "nameSearch", "in": "query", "schema": { "type": "string", "description": "Substring match against curator name." }, "required": false, "description": "Substring match against curator name." }, { "name": "playlistKeywordSearch", "in": "query", "schema": { "type": "string", "description": "Substring match against names of playlists owned by the curator." }, "required": false, "description": "Substring match against names of playlists owned by the curator." }, { "name": "code2", "in": "query", "schema": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB')." }, "required": false, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB')." }, { "name": "editorial", "in": "query", "schema": { "type": "boolean", "description": "If true, return only official platform editorial curators. If false, exclude them. Applies to `spotify`, `applemusic`, `amazon`, and `youtube`." }, "required": false, "description": "If true, return only official platform editorial curators. If false, exclude them. Applies to `spotify`, `applemusic`, `amazon`, and `youtube`." }, { "name": "indie", "in": "query", "schema": { "type": "boolean", "description": "If true, include curators that are not major-label, editorial, brand, or popular indie. If false, exclude them. Applies to `spotify`, `applemusic`, and `youtube`." }, "required": false, "description": "If true, include curators that are not major-label, editorial, brand, or popular indie. If false, exclude them. Applies to `spotify`, `applemusic`, and `youtube`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "array", "items": { "type": "object", "properties": { "position": { "type": [ "integer", "null" ], "description": "1-based rank of the curator within the entire sorted result set (i.e. `index + 1 + offset`)." }, "owner_id": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "string" } ], "description": "Chartmetric curator ID. Numeric for `spotify`, `applemusic`, `itunes`, `deezer`, `amazon`; string for `youtube` (channel ID)." }, "owner_name": { "type": [ "string", "null" ], "description": "Curator display name." }, "url": { "type": [ "string", "null" ], "description": "Image or profile URL for the curator on the platform." }, "code2": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-2 country code associated with the curator (lowercase, e.g. 'us', 'gb'). Populated for `applemusic`, `itunes`, `deezer`, `youtube`." }, "tags": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Genre tags associated with the curator." }, "num_playlists": { "type": [ "integer", "null" ], "description": "Count of the curator's playlists tracked by Chartmetric." }, "user_id": { "type": [ "string", "null" ], "description": "Platform-side user ID (Spotify user)." }, "sp_playlist_total_reach": { "type": [ "integer", "null" ], "description": "Sum of followers across all of this Spotify curator's playlists (total playlist reach). Spotify only." }, "followers": { "type": [ "integer", "null" ], "description": "Curator's follower count on the platform." }, "fdiff_month": { "type": [ "integer", "null" ], "description": "Net change in followers vs. 28 days ago. Spotify only." }, "fdiff_percent_month": { "type": [ "number", "null" ], "format": "float", "description": "Percentage change in followers vs. 28 days ago, expressed as a fraction (e.g. 0.0139 = +1.39%). Spotify only." }, "num_updates": { "type": [ "integer", "null" ], "description": "Number of updates the curator has made across their playlists. Spotify only." }, "num_tracks_updated": { "type": [ "integer", "null" ], "description": "Number of tracks added/removed across the curator's recent playlist updates. Spotify only." }, "editorial": { "type": [ "boolean", "null" ], "description": "True if this is an official platform editorial curator." }, "major_label": { "type": [ "boolean", "null" ], "description": "True if the curator is operated by a major label (Sony, Universal, Warner)." }, "brand": { "type": [ "boolean", "null" ], "description": "True if the curator is operated by a brand." }, "popular_indie": { "type": [ "boolean", "null" ], "description": "True if the curator is a popular indie (not editorial/brand/major-label, with 100K+ reached followers)." }, "indie": { "type": [ "boolean", "null" ], "description": "True if the curator is independent (not editorial, brand, major-label, or popular indie)." }, "audiobook": { "type": [ "boolean", "null" ], "description": "True if the curator focuses on audiobook content." }, "suspicion_score": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric suspicion score flagging potentially inauthentic activity (lower is cleaner). Spotify only." }, "total_reach": { "type": [ "integer", "null" ], "description": "Sum of followers across all of this curator's Deezer playlists. Deezer only." }, "total_playlists": { "type": [ "integer", "null" ], "description": "Total number of playlists owned by this curator on Amazon Music. Amazon only." }, "curator_id": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "string" } ], "nullable": true, "description": "Platform-side curator ID on Apple Music / iTunes." }, "channel_views": { "type": [ "integer", "null" ], "description": "Cumulative views across the curator's YouTube channel. YouTube only." }, "channel_subscribers": { "type": [ "integer", "null" ], "description": "Subscriber count for the curator's YouTube channel. YouTube only." }, "total_playlist_views": { "type": [ "integer", "null" ], "description": "Sum of views across all of the curator's YouTube playlists. YouTube only." } } }, "description": "List of curator entries for the requested platform." }, "offset": { "type": [ "integer", "null" ], "description": "Offset of this result page (echoes the `offset` request param)." }, "total": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "nullable": true, "description": "Total number of curators matching the filters across all pages." } }, "required": [ "obj" ] }, "examples": { "default": { "value": { "obj": [ { "owner_id": 1, "owner_name": "Apple Music", "url": "https://is1-ssl.mzstatic.com/image/thumb/Features126/v4/...jpg", "code2": "us", "curator_id": 976439548, "num_playlists": 2500, "tags": [ "Pop", "Rock" ] } ], "offset": 0, "total": 500 } } } } } } } } }, "/api/curator/applemusic/lists": { "get": { "summary": "List Apple Music Curators", "tags": [ "Curator" ], "operationId": "listCuratorsAppleMusic", "description": "List curators by platform. Sort columns vary by platform: `spotify` — `num_playlists` (default), `followers`, `num_updates`, `num_tracks_updated`, `fdiff_month`, `fdiff_percent_month`, `sp_playlist_total_reach`; `applemusic`/`itunes` — `num_playlists` (default); `deezer` — `num_playlists`, `total_reach` (default); `youtube` — `total_playlist_views` (default), `num_playlists`, `channel_views`, `channel_subscribers`; `amazon` — `total_playlists` (default). Note: `applemusic` and `itunes` return the same data.", "parameters": [ { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate. `offset + limit` must be ≤ 10,000 (Elasticsearch window)." }, "required": false, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate. `offset + limit` must be ≤ 10,000 (Elasticsearch window)." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 0, "description": "Maximum number of curators to return per request. Defaults to 50; max 10000. `offset + limit` must be ≤ 10,000.", "default": 50 }, "required": false, "description": "Maximum number of curators to return per request. Defaults to 50; max 10000. `offset + limit` must be ≤ 10,000." }, { "name": "sortColumn", "in": "query", "schema": { "type": "string", "enum": [ "num_playlists" ], "description": "Column to sort curators by. Allowed values vary per platform; see the endpoint description for the list. Default also varies per platform.", "default": "num_playlists" }, "required": false, "description": "Column to sort curators by. Allowed values vary per platform; see the endpoint description for the list. Default also varies per platform." }, { "name": "sortOrderDesc", "in": "query", "schema": { "type": "boolean", "description": "If true, sort `sortColumn` in descending order. Defaults to true.", "default": true }, "required": false, "description": "If true, sort `sortColumn` in descending order. Defaults to true." }, { "name": "userListIds[]", "in": "query", "schema": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "uniqueItems": true, "description": "Filter by Chartmetric shortlist (user list) IDs the curator is included on. Public API exposes this as `shortlistIds`." }, "required": false, "description": "Filter by Chartmetric shortlist (user list) IDs the curator is included on. Public API exposes this as `shortlistIds`." }, { "name": "nameSearch", "in": "query", "schema": { "type": "string", "description": "Substring match against curator name." }, "required": false, "description": "Substring match against curator name." }, { "name": "playlistKeywordSearch", "in": "query", "schema": { "type": "string", "description": "Substring match against names of playlists owned by the curator." }, "required": false, "description": "Substring match against names of playlists owned by the curator." }, { "name": "code2", "in": "query", "schema": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB')." }, "required": false, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB')." }, { "name": "editorial", "in": "query", "schema": { "type": "boolean", "description": "If true, return only official platform editorial curators. If false, exclude them. Applies to `spotify`, `applemusic`, `amazon`, and `youtube`." }, "required": false, "description": "If true, return only official platform editorial curators. If false, exclude them. Applies to `spotify`, `applemusic`, `amazon`, and `youtube`." }, { "name": "indie", "in": "query", "schema": { "type": "boolean", "description": "If true, include curators that are not major-label, editorial, brand, or popular indie. If false, exclude them. Applies to `spotify`, `applemusic`, and `youtube`." }, "required": false, "description": "If true, include curators that are not major-label, editorial, brand, or popular indie. If false, exclude them. Applies to `spotify`, `applemusic`, and `youtube`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "array", "items": { "type": "object", "properties": { "position": { "type": [ "integer", "null" ], "description": "1-based rank of the curator within the entire sorted result set (i.e. `index + 1 + offset`)." }, "owner_id": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "string" } ], "description": "Chartmetric curator ID. Numeric for `spotify`, `applemusic`, `itunes`, `deezer`, `amazon`; string for `youtube` (channel ID)." }, "owner_name": { "type": [ "string", "null" ], "description": "Curator display name." }, "url": { "type": [ "string", "null" ], "description": "Image or profile URL for the curator on the platform." }, "code2": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-2 country code associated with the curator (lowercase, e.g. 'us', 'gb'). Populated for `applemusic`, `itunes`, `deezer`, `youtube`." }, "tags": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Genre tags associated with the curator." }, "num_playlists": { "type": [ "integer", "null" ], "description": "Count of the curator's playlists tracked by Chartmetric." }, "user_id": { "type": [ "string", "null" ], "description": "Platform-side user ID (Spotify user)." }, "sp_playlist_total_reach": { "type": [ "integer", "null" ], "description": "Sum of followers across all of this Spotify curator's playlists (total playlist reach). Spotify only." }, "followers": { "type": [ "integer", "null" ], "description": "Curator's follower count on the platform." }, "fdiff_month": { "type": [ "integer", "null" ], "description": "Net change in followers vs. 28 days ago. Spotify only." }, "fdiff_percent_month": { "type": [ "number", "null" ], "format": "float", "description": "Percentage change in followers vs. 28 days ago, expressed as a fraction (e.g. 0.0139 = +1.39%). Spotify only." }, "num_updates": { "type": [ "integer", "null" ], "description": "Number of updates the curator has made across their playlists. Spotify only." }, "num_tracks_updated": { "type": [ "integer", "null" ], "description": "Number of tracks added/removed across the curator's recent playlist updates. Spotify only." }, "editorial": { "type": [ "boolean", "null" ], "description": "True if this is an official platform editorial curator." }, "major_label": { "type": [ "boolean", "null" ], "description": "True if the curator is operated by a major label (Sony, Universal, Warner)." }, "brand": { "type": [ "boolean", "null" ], "description": "True if the curator is operated by a brand." }, "popular_indie": { "type": [ "boolean", "null" ], "description": "True if the curator is a popular indie (not editorial/brand/major-label, with 100K+ reached followers)." }, "indie": { "type": [ "boolean", "null" ], "description": "True if the curator is independent (not editorial, brand, major-label, or popular indie)." }, "audiobook": { "type": [ "boolean", "null" ], "description": "True if the curator focuses on audiobook content." }, "suspicion_score": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric suspicion score flagging potentially inauthentic activity (lower is cleaner). Spotify only." }, "total_reach": { "type": [ "integer", "null" ], "description": "Sum of followers across all of this curator's Deezer playlists. Deezer only." }, "total_playlists": { "type": [ "integer", "null" ], "description": "Total number of playlists owned by this curator on Amazon Music. Amazon only." }, "curator_id": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "string" } ], "nullable": true, "description": "Platform-side curator ID on Apple Music / iTunes." }, "channel_views": { "type": [ "integer", "null" ], "description": "Cumulative views across the curator's YouTube channel. YouTube only." }, "channel_subscribers": { "type": [ "integer", "null" ], "description": "Subscriber count for the curator's YouTube channel. YouTube only." }, "total_playlist_views": { "type": [ "integer", "null" ], "description": "Sum of views across all of the curator's YouTube playlists. YouTube only." } } }, "description": "List of curator entries for the requested platform." }, "offset": { "type": [ "integer", "null" ], "description": "Offset of this result page (echoes the `offset` request param)." }, "total": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "nullable": true, "description": "Total number of curators matching the filters across all pages." } }, "required": [ "obj" ] }, "examples": { "default": { "value": { "obj": [ { "owner_id": 1, "owner_name": "Apple Music", "url": "https://is1-ssl.mzstatic.com/image/thumb/Features126/v4/...jpg", "code2": "us", "curator_id": 976439548, "num_playlists": 2500, "tags": [ "Pop", "Rock" ] } ], "offset": 0, "total": 500 } } } } } } } } }, "/api/curator/spotify/lists": { "get": { "summary": "List Spotify Curators", "tags": [ "Curator" ], "operationId": "listCuratorsSpotify", "description": "List curators by platform. Sort columns vary by platform: `spotify` — `num_playlists` (default), `followers`, `num_updates`, `num_tracks_updated`, `fdiff_month`, `fdiff_percent_month`, `sp_playlist_total_reach`; `applemusic`/`itunes` — `num_playlists` (default); `deezer` — `num_playlists`, `total_reach` (default); `youtube` — `total_playlist_views` (default), `num_playlists`, `channel_views`, `channel_subscribers`; `amazon` — `total_playlists` (default).", "parameters": [ { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate. `offset + limit` must be ≤ 10,000 (Elasticsearch window)." }, "required": false, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate. `offset + limit` must be ≤ 10,000 (Elasticsearch window)." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 0, "description": "Maximum number of curators to return per request. Defaults to 50; max 10000. `offset + limit` must be ≤ 10,000.", "default": 50 }, "required": false, "description": "Maximum number of curators to return per request. Defaults to 50; max 10000. `offset + limit` must be ≤ 10,000." }, { "name": "sortColumn", "in": "query", "schema": { "type": "string", "enum": [ "num_playlists", "followers", "num_updates", "num_tracks_updated", "fdiff_month", "fdiff_percent_month", "sp_playlist_total_reach" ], "description": "Column to sort curators by. Allowed values vary per platform; see the endpoint description for the list. Default also varies per platform.", "default": "sp_playlist_total_reach" }, "required": false, "description": "Column to sort curators by. Allowed values vary per platform; see the endpoint description for the list. Default also varies per platform." }, { "name": "sortOrderDesc", "in": "query", "schema": { "type": "boolean", "description": "If true, sort `sortColumn` in descending order. Defaults to true.", "default": true }, "required": false, "description": "If true, sort `sortColumn` in descending order. Defaults to true." }, { "name": "userListIds[]", "in": "query", "schema": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "uniqueItems": true, "description": "Filter by Chartmetric shortlist (user list) IDs the curator is included on. Public API exposes this as `shortlistIds`." }, "required": false, "description": "Filter by Chartmetric shortlist (user list) IDs the curator is included on. Public API exposes this as `shortlistIds`." }, { "name": "nameSearch", "in": "query", "schema": { "type": "string", "description": "Substring match against curator name." }, "required": false, "description": "Substring match against curator name." }, { "name": "playlistKeywordSearch", "in": "query", "schema": { "type": "string", "description": "Substring match against names of playlists owned by the curator." }, "required": false, "description": "Substring match against names of playlists owned by the curator." }, { "name": "withSocialUrls", "in": "query", "schema": { "type": "boolean", "description": "If true, return only curators that have social URL data on file (URLs themselves are not included in the response). Applies to `spotify` only.", "default": false }, "required": false, "description": "If true, return only curators that have social URL data on file (URLs themselves are not included in the response). Applies to `spotify` only." }, { "name": "editorial", "in": "query", "schema": { "type": "boolean", "description": "If true, return only official platform editorial curators. If false, exclude them. Applies to `spotify`, `applemusic`, `amazon`, and `youtube`." }, "required": false, "description": "If true, return only official platform editorial curators. If false, exclude them. Applies to `spotify`, `applemusic`, `amazon`, and `youtube`." }, { "name": "majorLabel", "in": "query", "schema": { "type": "boolean", "description": "If true, return only major-label curators (Sony, Universal, Warner). If false, exclude them. Applies to `spotify` and `youtube`." }, "required": false, "description": "If true, return only major-label curators (Sony, Universal, Warner). If false, exclude them. Applies to `spotify` and `youtube`." }, { "name": "brand", "in": "query", "schema": { "type": "boolean", "description": "If true, return only curators associated with a brand. If false, exclude them. Applies to `spotify` and `youtube`." }, "required": false, "description": "If true, return only curators associated with a brand. If false, exclude them. Applies to `spotify` and `youtube`." }, { "name": "popularIndie", "in": "query", "schema": { "type": "boolean", "description": "If true, return only popular indie curators (not editorial/brand/major-label, with 100K+ reached followers). If false, exclude them. Applies to `spotify` and `youtube`." }, "required": false, "description": "If true, return only popular indie curators (not editorial/brand/major-label, with 100K+ reached followers). If false, exclude them. Applies to `spotify` and `youtube`." }, { "name": "indie", "in": "query", "schema": { "type": "boolean", "description": "If true, include curators that are not major-label, editorial, brand, or popular indie. If false, exclude them. Applies to `spotify`, `applemusic`, and `youtube`." }, "required": false, "description": "If true, include curators that are not major-label, editorial, brand, or popular indie. If false, exclude them. Applies to `spotify`, `applemusic`, and `youtube`." }, { "name": "audiobook", "in": "query", "schema": { "type": "boolean", "description": "If true, return only audiobook curators. If false, exclude them. Applies to `spotify` and `youtube`." }, "required": false, "description": "If true, return only audiobook curators. If false, exclude them. Applies to `spotify` and `youtube`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "array", "items": { "type": "object", "properties": { "position": { "type": [ "integer", "null" ], "description": "1-based rank of the curator within the entire sorted result set (i.e. `index + 1 + offset`)." }, "owner_id": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "string" } ], "description": "Chartmetric curator ID. Numeric for `spotify`, `applemusic`, `itunes`, `deezer`, `amazon`; string for `youtube` (channel ID)." }, "owner_name": { "type": [ "string", "null" ], "description": "Curator display name." }, "url": { "type": [ "string", "null" ], "description": "Image or profile URL for the curator on the platform." }, "code2": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-2 country code associated with the curator (lowercase, e.g. 'us', 'gb'). Populated for `applemusic`, `itunes`, `deezer`, `youtube`." }, "tags": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Genre tags associated with the curator." }, "num_playlists": { "type": [ "integer", "null" ], "description": "Count of the curator's playlists tracked by Chartmetric." }, "user_id": { "type": [ "string", "null" ], "description": "Platform-side user ID (Spotify user)." }, "sp_playlist_total_reach": { "type": [ "integer", "null" ], "description": "Sum of followers across all of this Spotify curator's playlists (total playlist reach). Spotify only." }, "followers": { "type": [ "integer", "null" ], "description": "Curator's follower count on the platform." }, "fdiff_month": { "type": [ "integer", "null" ], "description": "Net change in followers vs. 28 days ago. Spotify only." }, "fdiff_percent_month": { "type": [ "number", "null" ], "format": "float", "description": "Percentage change in followers vs. 28 days ago, expressed as a fraction (e.g. 0.0139 = +1.39%). Spotify only." }, "num_updates": { "type": [ "integer", "null" ], "description": "Number of updates the curator has made across their playlists. Spotify only." }, "num_tracks_updated": { "type": [ "integer", "null" ], "description": "Number of tracks added/removed across the curator's recent playlist updates. Spotify only." }, "editorial": { "type": [ "boolean", "null" ], "description": "True if this is an official platform editorial curator." }, "major_label": { "type": [ "boolean", "null" ], "description": "True if the curator is operated by a major label (Sony, Universal, Warner)." }, "brand": { "type": [ "boolean", "null" ], "description": "True if the curator is operated by a brand." }, "popular_indie": { "type": [ "boolean", "null" ], "description": "True if the curator is a popular indie (not editorial/brand/major-label, with 100K+ reached followers)." }, "indie": { "type": [ "boolean", "null" ], "description": "True if the curator is independent (not editorial, brand, major-label, or popular indie)." }, "audiobook": { "type": [ "boolean", "null" ], "description": "True if the curator focuses on audiobook content." }, "suspicion_score": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric suspicion score flagging potentially inauthentic activity (lower is cleaner). Spotify only." }, "total_reach": { "type": [ "integer", "null" ], "description": "Sum of followers across all of this curator's Deezer playlists. Deezer only." }, "total_playlists": { "type": [ "integer", "null" ], "description": "Total number of playlists owned by this curator on Amazon Music. Amazon only." }, "curator_id": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "string" } ], "nullable": true, "description": "Platform-side curator ID on Apple Music / iTunes." }, "channel_views": { "type": [ "integer", "null" ], "description": "Cumulative views across the curator's YouTube channel. YouTube only." }, "channel_subscribers": { "type": [ "integer", "null" ], "description": "Subscriber count for the curator's YouTube channel. YouTube only." }, "total_playlist_views": { "type": [ "integer", "null" ], "description": "Sum of views across all of the curator's YouTube playlists. YouTube only." } } }, "description": "List of curator entries for the requested platform." }, "offset": { "type": [ "integer", "null" ], "description": "Offset of this result page (echoes the `offset` request param)." }, "total": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "nullable": true, "description": "Total number of curators matching the filters across all pages." } }, "required": [ "obj" ] }, "examples": { "default": { "value": { "obj": [ { "position": 1, "user_id": "spotify", "owner_id": 2, "owner_name": "Spotify", "url": "https://i.scdn.co/image/ab6775700000ee8555c25988a6ac314394d3fbf5", "num_playlists": 138039, "sp_playlist_total_reach": 2793372862, "followers": 11213310, "fdiff_month": 113368, "fdiff_percent_month": 0.013958, "tags": [ "pop", "hip-hop/rap", "rock" ], "num_updates": 0, "num_tracks_updated": 0, "editorial": true, "major_label": false, "brand": false, "popular_indie": false, "indie": false, "audiobook": true } ], "offset": 0, "total": 2712006 } } } } } } } } }, "/api/curator/youtube/lists": { "get": { "summary": "List YouTube Curators", "tags": [ "Curator" ], "operationId": "listCuratorsYoutube", "description": "List curators by platform. Sort columns vary by platform: `spotify` — `num_playlists` (default), `followers`, `num_updates`, `num_tracks_updated`, `fdiff_month`, `fdiff_percent_month`, `sp_playlist_total_reach`; `applemusic`/`itunes` — `num_playlists` (default); `deezer` — `num_playlists`, `total_reach` (default); `youtube` — `total_playlist_views` (default), `num_playlists`, `channel_views`, `channel_subscribers`; `amazon` — `total_playlists` (default).", "parameters": [ { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate. `offset + limit` must be ≤ 10,000 (Elasticsearch window)." }, "required": false, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate. `offset + limit` must be ≤ 10,000 (Elasticsearch window)." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 0, "description": "Maximum number of curators to return per request. Defaults to 50; max 10000. `offset + limit` must be ≤ 10,000.", "default": 50 }, "required": false, "description": "Maximum number of curators to return per request. Defaults to 50; max 10000. `offset + limit` must be ≤ 10,000." }, { "name": "sortColumn", "in": "query", "schema": { "type": "string", "enum": [ "channel_subscribers", "channel_views", "num_playlists", "total_playlist_views" ], "description": "Column to sort curators by. Allowed values vary per platform; see the endpoint description for the list. Default also varies per platform.", "default": "channel_subscribers" }, "required": false, "description": "Column to sort curators by. Allowed values vary per platform; see the endpoint description for the list. Default also varies per platform." }, { "name": "sortOrderDesc", "in": "query", "schema": { "type": "boolean", "description": "If true, sort `sortColumn` in descending order. Defaults to true.", "default": true }, "required": false, "description": "If true, sort `sortColumn` in descending order. Defaults to true." }, { "name": "userListIds[]", "in": "query", "schema": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "uniqueItems": true, "description": "Filter by Chartmetric shortlist (user list) IDs the curator is included on. Public API exposes this as `shortlistIds`." }, "required": false, "description": "Filter by Chartmetric shortlist (user list) IDs the curator is included on. Public API exposes this as `shortlistIds`." }, { "name": "nameSearch", "in": "query", "schema": { "type": "string", "description": "Substring match against curator name." }, "required": false, "description": "Substring match against curator name." }, { "name": "playlistKeywordSearch", "in": "query", "schema": { "type": "string", "description": "Substring match against names of playlists owned by the curator." }, "required": false, "description": "Substring match against names of playlists owned by the curator." }, { "name": "code2", "in": "query", "schema": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB')." }, "required": false, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB')." }, { "name": "editorial", "in": "query", "schema": { "type": "boolean", "description": "If true, return only official platform editorial curators. If false, exclude them. Applies to `spotify`, `applemusic`, `amazon`, and `youtube`." }, "required": false, "description": "If true, return only official platform editorial curators. If false, exclude them. Applies to `spotify`, `applemusic`, `amazon`, and `youtube`." }, { "name": "majorLabel", "in": "query", "schema": { "type": "boolean", "description": "If true, return only major-label curators (Sony, Universal, Warner). If false, exclude them. Applies to `spotify` and `youtube`." }, "required": false, "description": "If true, return only major-label curators (Sony, Universal, Warner). If false, exclude them. Applies to `spotify` and `youtube`." }, { "name": "brand", "in": "query", "schema": { "type": "boolean", "description": "If true, return only curators associated with a brand. If false, exclude them. Applies to `spotify` and `youtube`." }, "required": false, "description": "If true, return only curators associated with a brand. If false, exclude them. Applies to `spotify` and `youtube`." }, { "name": "popularIndie", "in": "query", "schema": { "type": "boolean", "description": "If true, return only popular indie curators (not editorial/brand/major-label, with 100K+ reached followers). If false, exclude them. Applies to `spotify` and `youtube`." }, "required": false, "description": "If true, return only popular indie curators (not editorial/brand/major-label, with 100K+ reached followers). If false, exclude them. Applies to `spotify` and `youtube`." }, { "name": "indie", "in": "query", "schema": { "type": "boolean", "description": "If true, include curators that are not major-label, editorial, brand, or popular indie. If false, exclude them. Applies to `spotify`, `applemusic`, and `youtube`." }, "required": false, "description": "If true, include curators that are not major-label, editorial, brand, or popular indie. If false, exclude them. Applies to `spotify`, `applemusic`, and `youtube`." }, { "name": "audiobook", "in": "query", "schema": { "type": "boolean", "description": "If true, return only audiobook curators. If false, exclude them. Applies to `spotify` and `youtube`." }, "required": false, "description": "If true, return only audiobook curators. If false, exclude them. Applies to `spotify` and `youtube`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "array", "items": { "type": "object", "properties": { "position": { "type": [ "integer", "null" ], "description": "1-based rank of the curator within the entire sorted result set (i.e. `index + 1 + offset`)." }, "owner_id": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "string" } ], "description": "Chartmetric curator ID. Numeric for `spotify`, `applemusic`, `itunes`, `deezer`, `amazon`; string for `youtube` (channel ID)." }, "owner_name": { "type": [ "string", "null" ], "description": "Curator display name." }, "url": { "type": [ "string", "null" ], "description": "Image or profile URL for the curator on the platform." }, "code2": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-2 country code associated with the curator (lowercase, e.g. 'us', 'gb'). Populated for `applemusic`, `itunes`, `deezer`, `youtube`." }, "tags": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Genre tags associated with the curator." }, "num_playlists": { "type": [ "integer", "null" ], "description": "Count of the curator's playlists tracked by Chartmetric." }, "user_id": { "type": [ "string", "null" ], "description": "Platform-side user ID (Spotify user)." }, "sp_playlist_total_reach": { "type": [ "integer", "null" ], "description": "Sum of followers across all of this Spotify curator's playlists (total playlist reach). Spotify only." }, "followers": { "type": [ "integer", "null" ], "description": "Curator's follower count on the platform." }, "fdiff_month": { "type": [ "integer", "null" ], "description": "Net change in followers vs. 28 days ago. Spotify only." }, "fdiff_percent_month": { "type": [ "number", "null" ], "format": "float", "description": "Percentage change in followers vs. 28 days ago, expressed as a fraction (e.g. 0.0139 = +1.39%). Spotify only." }, "num_updates": { "type": [ "integer", "null" ], "description": "Number of updates the curator has made across their playlists. Spotify only." }, "num_tracks_updated": { "type": [ "integer", "null" ], "description": "Number of tracks added/removed across the curator's recent playlist updates. Spotify only." }, "editorial": { "type": [ "boolean", "null" ], "description": "True if this is an official platform editorial curator." }, "major_label": { "type": [ "boolean", "null" ], "description": "True if the curator is operated by a major label (Sony, Universal, Warner)." }, "brand": { "type": [ "boolean", "null" ], "description": "True if the curator is operated by a brand." }, "popular_indie": { "type": [ "boolean", "null" ], "description": "True if the curator is a popular indie (not editorial/brand/major-label, with 100K+ reached followers)." }, "indie": { "type": [ "boolean", "null" ], "description": "True if the curator is independent (not editorial, brand, major-label, or popular indie)." }, "audiobook": { "type": [ "boolean", "null" ], "description": "True if the curator focuses on audiobook content." }, "suspicion_score": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric suspicion score flagging potentially inauthentic activity (lower is cleaner). Spotify only." }, "total_reach": { "type": [ "integer", "null" ], "description": "Sum of followers across all of this curator's Deezer playlists. Deezer only." }, "total_playlists": { "type": [ "integer", "null" ], "description": "Total number of playlists owned by this curator on Amazon Music. Amazon only." }, "curator_id": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "string" } ], "nullable": true, "description": "Platform-side curator ID on Apple Music / iTunes." }, "channel_views": { "type": [ "integer", "null" ], "description": "Cumulative views across the curator's YouTube channel. YouTube only." }, "channel_subscribers": { "type": [ "integer", "null" ], "description": "Subscriber count for the curator's YouTube channel. YouTube only." }, "total_playlist_views": { "type": [ "integer", "null" ], "description": "Sum of views across all of the curator's YouTube playlists. YouTube only." } } }, "description": "List of curator entries for the requested platform." }, "offset": { "type": [ "integer", "null" ], "description": "Offset of this result page (echoes the `offset` request param)." }, "total": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "nullable": true, "description": "Total number of curators matching the filters across all pages." } }, "required": [ "obj" ] }, "examples": { "default": { "value": { "obj": [ { "position": 1, "owner_id": "UC-9-kyTW8ZkZNDHQJ6FgpwQ", "url": "https://yt3.googleusercontent.com/...", "owner_name": "Music", "channel_views": 123456789, "channel_subscribers": 100000000, "total_playlist_views": 987654321, "num_playlists": 52, "tags": [ "pop", "rock" ] } ], "offset": 0, "total": 1000 } } } } } } } } }, "/api/curator/amazon/lists": { "get": { "summary": "List Amazon Curators", "tags": [ "Curator" ], "operationId": "listCuratorsAmazon", "description": "List curators by platform. Sort columns vary by platform: `spotify` — `num_playlists` (default), `followers`, `num_updates`, `num_tracks_updated`, `fdiff_month`, `fdiff_percent_month`, `sp_playlist_total_reach`; `applemusic`/`itunes` — `num_playlists` (default); `deezer` — `num_playlists`, `total_reach` (default); `youtube` — `total_playlist_views` (default), `num_playlists`, `channel_views`, `channel_subscribers`; `amazon` — `total_playlists` (default).", "parameters": [ { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate. `offset + limit` must be ≤ 10,000 (Elasticsearch window)." }, "required": false, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate. `offset + limit` must be ≤ 10,000 (Elasticsearch window)." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 0, "description": "Maximum number of curators to return per request. Defaults to 50; max 10000. `offset + limit` must be ≤ 10,000.", "default": 50 }, "required": false, "description": "Maximum number of curators to return per request. Defaults to 50; max 10000. `offset + limit` must be ≤ 10,000." }, { "name": "sortColumn", "in": "query", "schema": { "type": "string", "enum": [ "total_playlists" ], "description": "Column to sort curators by. Allowed values vary per platform; see the endpoint description for the list. Default also varies per platform.", "default": "total_playlists" }, "required": false, "description": "Column to sort curators by. Allowed values vary per platform; see the endpoint description for the list. Default also varies per platform." }, { "name": "sortOrderDesc", "in": "query", "schema": { "type": "boolean", "description": "If true, sort `sortColumn` in descending order. Defaults to true.", "default": true }, "required": false, "description": "If true, sort `sortColumn` in descending order. Defaults to true." }, { "name": "userListIds[]", "in": "query", "schema": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "uniqueItems": true, "description": "Filter by Chartmetric shortlist (user list) IDs the curator is included on. Public API exposes this as `shortlistIds`." }, "required": false, "description": "Filter by Chartmetric shortlist (user list) IDs the curator is included on. Public API exposes this as `shortlistIds`." }, { "name": "nameSearch", "in": "query", "schema": { "type": "string", "description": "Substring match against curator name." }, "required": false, "description": "Substring match against curator name." }, { "name": "playlistKeywordSearch", "in": "query", "schema": { "type": "string", "description": "Substring match against names of playlists owned by the curator." }, "required": false, "description": "Substring match against names of playlists owned by the curator." }, { "name": "editorial", "in": "query", "schema": { "type": "boolean", "description": "If true, return only official platform editorial curators. If false, exclude them. Applies to `spotify`, `applemusic`, `amazon`, and `youtube`." }, "required": false, "description": "If true, return only official platform editorial curators. If false, exclude them. Applies to `spotify`, `applemusic`, `amazon`, and `youtube`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "array", "items": { "type": "object", "properties": { "position": { "type": [ "integer", "null" ], "description": "1-based rank of the curator within the entire sorted result set (i.e. `index + 1 + offset`)." }, "owner_id": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "string" } ], "description": "Chartmetric curator ID. Numeric for `spotify`, `applemusic`, `itunes`, `deezer`, `amazon`; string for `youtube` (channel ID)." }, "owner_name": { "type": [ "string", "null" ], "description": "Curator display name." }, "url": { "type": [ "string", "null" ], "description": "Image or profile URL for the curator on the platform." }, "code2": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-2 country code associated with the curator (lowercase, e.g. 'us', 'gb'). Populated for `applemusic`, `itunes`, `deezer`, `youtube`." }, "tags": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Genre tags associated with the curator." }, "num_playlists": { "type": [ "integer", "null" ], "description": "Count of the curator's playlists tracked by Chartmetric." }, "user_id": { "type": [ "string", "null" ], "description": "Platform-side user ID (Spotify user)." }, "sp_playlist_total_reach": { "type": [ "integer", "null" ], "description": "Sum of followers across all of this Spotify curator's playlists (total playlist reach). Spotify only." }, "followers": { "type": [ "integer", "null" ], "description": "Curator's follower count on the platform." }, "fdiff_month": { "type": [ "integer", "null" ], "description": "Net change in followers vs. 28 days ago. Spotify only." }, "fdiff_percent_month": { "type": [ "number", "null" ], "format": "float", "description": "Percentage change in followers vs. 28 days ago, expressed as a fraction (e.g. 0.0139 = +1.39%). Spotify only." }, "num_updates": { "type": [ "integer", "null" ], "description": "Number of updates the curator has made across their playlists. Spotify only." }, "num_tracks_updated": { "type": [ "integer", "null" ], "description": "Number of tracks added/removed across the curator's recent playlist updates. Spotify only." }, "editorial": { "type": [ "boolean", "null" ], "description": "True if this is an official platform editorial curator." }, "major_label": { "type": [ "boolean", "null" ], "description": "True if the curator is operated by a major label (Sony, Universal, Warner)." }, "brand": { "type": [ "boolean", "null" ], "description": "True if the curator is operated by a brand." }, "popular_indie": { "type": [ "boolean", "null" ], "description": "True if the curator is a popular indie (not editorial/brand/major-label, with 100K+ reached followers)." }, "indie": { "type": [ "boolean", "null" ], "description": "True if the curator is independent (not editorial, brand, major-label, or popular indie)." }, "audiobook": { "type": [ "boolean", "null" ], "description": "True if the curator focuses on audiobook content." }, "suspicion_score": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric suspicion score flagging potentially inauthentic activity (lower is cleaner). Spotify only." }, "total_reach": { "type": [ "integer", "null" ], "description": "Sum of followers across all of this curator's Deezer playlists. Deezer only." }, "total_playlists": { "type": [ "integer", "null" ], "description": "Total number of playlists owned by this curator on Amazon Music. Amazon only." }, "curator_id": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "string" } ], "nullable": true, "description": "Platform-side curator ID on Apple Music / iTunes." }, "channel_views": { "type": [ "integer", "null" ], "description": "Cumulative views across the curator's YouTube channel. YouTube only." }, "channel_subscribers": { "type": [ "integer", "null" ], "description": "Subscriber count for the curator's YouTube channel. YouTube only." }, "total_playlist_views": { "type": [ "integer", "null" ], "description": "Sum of views across all of the curator's YouTube playlists. YouTube only." } } }, "description": "List of curator entries for the requested platform." }, "offset": { "type": [ "integer", "null" ], "description": "Offset of this result page (echoes the `offset` request param)." }, "total": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "nullable": true, "description": "Total number of curators matching the filters across all pages." } }, "required": [ "obj" ] }, "examples": { "default": { "value": { "obj": [ { "position": 1, "total_playlists": 1200, "owner_id": 42, "owner_name": "Amazon Music", "tags": [ "Pop", "Rock" ] } ], "offset": 0, "total": 200 } } } } } } } } }, "/api/curator/{platform}/{id}": { "get": { "summary": "Get Curator Metadata", "tags": [ "Curator" ], "operationId": "getCuratorByPlatformId", "description": "Get a curator's metadata (name, image, tags, cross-platform social stats) by `platform` and Chartmetric `id`. Supported platforms: `spotify`, `applemusic`, `deezer`, `amazon`, `youtube`.", "parameters": [ { "name": "platform", "in": "path", "schema": { "type": "string", "enum": [ "cm", "spotify", "itunes", "applemusic", "deezer", "shazam", "beatport", "amazon", "youtube", "tunefind", "soundcloud" ], "description": "Streaming platform. Curator metadata is supported on `spotify`, `applemusic`, `deezer`, `amazon`, `youtube`." }, "required": true, "description": "Streaming platform. Curator metadata is supported on `spotify`, `applemusic`, `deezer`, `amazon`, `youtube`.", "examples": { "default": { "value": "cm" } } }, { "name": "id", "in": "path", "schema": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric curator ID." }, "required": true, "description": "Chartmetric curator ID.", "examples": { "default": { "value": 1 } } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "string" } ], "description": "Chartmetric curator ID." }, "user_id": { "anyOf": [ { "type": "string" }, { "type": "integer", "minimum": 0 } ], "nullable": true, "description": "Platform-side user/channel ID (e.g. Spotify user, YouTube channel ID, Deezer user)." }, "name": { "type": [ "string", "null" ], "description": "Curator display name." }, "description": { "type": [ "string", "null" ], "description": "Free-form curator description (Apple Music only; null on other platforms)." }, "image_url": { "type": [ "string", "null" ], "description": "URL of the curator's profile image." }, "code2": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-2 country code associated with the curator (lowercase). Populated for Apple Music and Deezer." }, "last_updated": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO timestamp of the curator's most recent metadata refresh." }, "tag_ids": { "type": [ "array", "null" ], "items": { "type": [ "integer", "null" ] }, "description": "Chartmetric genre tag IDs for this curator (positionally aligned with `tag_names`)." }, "tag_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Genre tag names for this curator (positionally aligned with `tag_ids`)." }, "groover_url": { "type": [ "string", "null" ], "description": "Groover submission URL for this curator, when one is registered." }, "cm_statistics": { "type": [ "object", "null" ], "properties": { "num_sp_playlists": { "type": [ "integer", "null" ], "description": "Number of Spotify playlists owned by this curator." }, "sp_followers": { "type": [ "integer", "null" ], "description": "Curator's Spotify follower count." }, "max_sp_playlist_followers": { "type": [ "integer", "null" ], "description": "Maximum follower count among the curator's Spotify playlists." }, "sp_playlist_total_reach": { "type": [ "integer", "null" ], "description": "Sum of followers across all of the curator's Spotify playlists." }, "num_itunes_playlists": { "type": [ "integer", "null" ], "description": "Number of Apple Music / iTunes playlists owned by this curator." }, "num_de_playlists": { "type": [ "integer", "null" ], "description": "Number of Deezer playlists owned by this curator." } }, "description": "Aggregated playlist statistics for this curator. Field set varies per platform." }, "tags": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric genre tag ID." }, "name": { "type": "string", "description": "Genre tag name." } }, "required": [ "id", "name" ] }, "description": "Genre tags as `{id, name}` objects." }, "instagram_followers": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "string" } ], "nullable": true, "description": "Instagram follower count for the curator's linked account." }, "soundcloud_followers": { "type": [ "integer", "null" ], "description": "SoundCloud follower count for the curator's linked account." }, "facebook_fans": { "type": [ "integer", "null" ], "description": "Facebook page fans (likes) for the curator's linked page." }, "facebook_followers": { "type": [ "integer", "null" ], "description": "Facebook page followers for the curator's linked page." }, "youtube_views": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "string" } ], "nullable": true, "description": "Cumulative view count across the curator's YouTube channel." }, "youtube_subscribers": { "type": [ "integer", "null" ], "description": "Subscriber count for the curator's YouTube channel." }, "twitter_followers": { "type": [ "integer", "null" ], "description": "Twitter/X follower count for the curator's linked account." }, "twitter_retweets": { "type": [ "integer", "null" ], "description": "Cumulative retweet count for the curator's linked Twitter/X account." }, "tiktok_likes": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "string" } ], "nullable": true, "description": "Cumulative like count across the curator's TikTok account." }, "tiktok_followers": { "type": [ "integer", "null" ], "description": "TikTok follower count for the curator's linked account." }, "spotifySocialUrls": { "type": [ "array", "null" ], "items": { "type": "object", "properties": {} }, "description": "Spotify-discovered social URLs for the curator (e.g. linked Instagram, Twitter). Spotify only." }, "storefronts": { "type": [ "string", "null" ], "description": "Comma-separated list of Apple Music storefront codes where this curator is available. Apple Music only." }, "num_itunes_playlists": { "type": [ "integer", "null" ], "description": "Number of Apple Music / iTunes playlists owned by this curator. Apple Music only." } }, "required": [ "id" ] } }, "required": [ "obj" ], "additionalProperties": false }, "examples": { "default": { "value": { "obj": { "id": 2, "user_id": "spotify", "name": "Spotify", "image_url": "https://i.scdn.co/image/ab6775700000ee8555c25988a6ac314394d3fbf5", "last_updated": "2021-05-06T07:00:00.000Z", "cm_statistics": { "num_sp_playlists": 70967, "sp_followers": 9563979, "max_sp_playlist_followers": 27702406, "sp_playlist_total_reach": 2082364476 }, "tags": [ { "id": 103, "name": "folk" }, { "id": 112, "name": "rock" }, { "id": 114, "name": "classical" } ], "instagram_followers": 6622570, "soundcloud_followers": null, "facebook_fans": 22691516, "facebook_followers": 22772732, "youtube_views": "552256171", "youtube_subscribers": 1200000, "twitter_followers": 4181216, "twitter_retweets": 7110, "tiktok_likes": "834600", "tiktok_followers": 199000 } } } } } } } } } }, "/api/curator/{platform}/{id}/playlists": { "get": { "summary": "List Curator Playlists", "tags": [ "Curator" ], "operationId": "listCuratorPlaylists", "description": "Get playlists created by a curator. Sort columns by platform: `spotify` — `last_updated`, `followers` (default), `num_track`; `applemusic` — `last_updated` (default), `num_track`; `deezer` — `last_updated` (default), `followers`, `num_track`.", "parameters": [ { "name": "platform", "in": "path", "schema": { "type": "string", "enum": [ "cm", "spotify", "itunes", "applemusic", "deezer", "shazam", "beatport", "amazon", "youtube", "tunefind", "soundcloud" ], "description": "Streaming platform. Curator playlists are supported on `spotify`, `applemusic`, `deezer`." }, "required": true, "description": "Streaming platform. Curator playlists are supported on `spotify`, `applemusic`, `deezer`.", "examples": { "default": { "value": "cm" } } }, { "name": "id", "in": "path", "schema": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric curator ID." }, "required": true, "description": "Chartmetric curator ID.", "examples": { "default": { "value": 1 } } }, { "name": "storefront", "in": "query", "schema": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB').", "default": "us" }, "required": false, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB')." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "description": "Maximum number of items to return per request.", "default": 100 }, "required": false, "description": "Maximum number of items to return per request." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, "required": false, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, { "name": "sortColumn", "in": "query", "schema": { "anyOf": [ { "type": "string", "enum": [ "last_updated", "followers", "num_track" ] }, { "type": "string", "enum": [ "last_updated", "num_track" ] }, { "type": "string", "enum": [ "last_updated", "num_track", "followers" ] } ], "description": "Column to sort playlists by. Allowed values vary per platform — see the operation description for the per-platform list." }, "required": false, "description": "Column to sort playlists by. Allowed values vary per platform — see the operation description for the per-platform list." }, { "name": "sortOrderDesc", "in": "query", "schema": { "type": "boolean", "description": "If true, sort `sortColumn` in descending order. Only allowed when `sortColumn` is set. Defaults to true.", "default": true }, "required": false, "description": "If true, sort `sortColumn` in descending order. Only allowed when `sortColumn` is set. Defaults to true." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "total_length": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "nullable": true, "description": "Total number of playlists matching the request across all pages." }, "length": { "type": "integer", "minimum": 0, "description": "Number of playlists returned in this response page." }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "string" } ], "description": "Chartmetric playlist ID." }, "name": { "type": [ "string", "null" ], "description": "Playlist name." }, "playlist_id": { "type": [ "string", "null" ], "description": "Platform-side playlist ID (e.g. Spotify URI tail)." }, "description": { "type": [ "string", "null" ], "description": "Free-form playlist description from the platform." }, "image_url": { "type": [ "string", "null" ], "description": "URL of the playlist cover image." }, "sys_last_updated": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO timestamp of the most recent Chartmetric crawl of this playlist." }, "last_updated": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO timestamp of the most recent platform-side update to this playlist." }, "personalized": { "type": [ "boolean", "null" ], "description": "True if the playlist is personalized per listener (e.g. Discover Weekly)." }, "code2": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-2 country code associated with the playlist (lowercase)." }, "owner_name": { "type": [ "string", "null" ], "description": "Display name of the playlist's owner." }, "owner_id": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "string" } ], "nullable": true, "description": "Chartmetric ID of the playlist owner." }, "user_id": { "anyOf": [ { "type": "string" }, { "type": "integer", "minimum": 0 } ], "nullable": true, "description": "Platform-side ID of the playlist owner." }, "official": { "type": [ "boolean", "null" ], "description": "True if the playlist is an official platform editorial playlist." }, "tags": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric genre tag ID." }, "name": { "type": "string", "description": "Genre tag name." } }, "required": [ "id", "name" ] }, "description": "Genre tags applied to the playlist." }, "followers": { "type": [ "integer", "null" ], "description": "Playlist follower count on the platform." }, "num_track": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "nullable": true, "description": "Number of tracks currently on the playlist." }, "fdiff_week": { "type": [ "integer", "null" ], "description": "Net change in followers vs. 7 days ago." }, "fdiff_month": { "type": [ "integer", "null" ], "description": "Net change in followers vs. 28 days ago." }, "catalog": { "type": [ "string", "null" ], "description": "Track-catalog mix of the playlist (e.g. 'frontline', 'catalogue', 'mixed')." }, "active_ratio": { "type": [ "number", "null" ], "format": "float", "description": "Fraction of the playlist tracks that are currently active (0–1)." } }, "required": [ "id" ] }, "description": "List of playlists owned by the curator." } }, "required": [ "length", "data" ] }, "examples": { "default": { "value": { "total_length": "134", "length": 1, "data": [ { "id": 1667152, "name": "Dominican Republic Viral 50", "playlist_id": "37i9dQZEVXbJWZV7aRNQck", "description": "Your daily update of the most viral tracks in Dominican Republic.", "image_url": "https://charts-images.scdn.co/assets/locale_en/viral/daily/region_do_large.jpg", "sys_last_updated": "2020-11-04T09:17:40.488Z", "last_updated": "2020-11-04T09:17:39.956Z", "personalized": false, "code2": "do", "owner_name": "spotifycharts", "owner_id": 133000, "user_id": "spotifycharts", "official": true, "tags": [ { "id": 4280, "name": "latin" } ], "followers": 23896, "num_track": "50", "fdiff_week": 43, "fdiff_month": 322, "catalog": "frontline ", "active_ratio": 0 } ] } } } } } } } } }, "/api/curator/{platform}/{id}/urls": { "get": { "summary": "List Curator Social / Streaming URLs", "tags": [ "Curator" ], "operationId": "listCuratorSocialUrls", "description": "Get social media and streaming service URLs belonging to this curator. `url` is a string when a URL is known; the handler emits an empty array `[]` when SNS data has no URL for the domain.", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric curator ID." }, "required": true, "description": "Chartmetric curator ID.", "examples": { "default": { "value": 1 } } }, { "name": "platform", "in": "path", "schema": { "type": "string", "enum": [ "spotify", "applemusic", "deezer" ], "description": "Streaming platform. Social URLs are supported on `spotify`, `applemusic`, `deezer`." }, "required": true, "description": "Streaming platform. Social URLs are supported on `spotify`, `applemusic`, `deezer`.", "examples": { "default": { "value": "spotify" } } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string", "description": "Social or streaming domain key (e.g. 'youtube', 'facebook', 'instagram', 'spotify', 'website')." }, "url": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "nullable": true, "description": "URL string when known. The handler emits an empty array `[]` when the SNS record has no URL for this domain." } }, "required": [ "domain" ] }, "description": "List of `{domain, url}` entries for the curator's known social and streaming presence." } }, "required": [ "obj" ], "additionalProperties": false }, "examples": { "default": { "value": { "obj": [ { "domain": "youtube", "url": "https://www.youtube.com/channel/UC4sYm9wRMr4uUVln4DywKOg" }, { "domain": "website", "url": "https://filtr.com/" }, { "domain": "soundcloud", "url": "https://soundcloud.com/filtr" }, { "domain": "facebook", "url": "https://www.facebook.com/filtr/" }, { "domain": "instagram", "url": "https://www.instagram.com/filtr/" }, { "domain": "tiktok", "url": "https://www.tiktok.com/@filtr.music" }, { "domain": "spotify", "url": "https://open.spotify.com/user/myplay.com" } ] } } } } } } } } }, "/api/curator/{platform}/{id}/stat/{source}": { "get": { "summary": "Get Curator Fan Metrics", "tags": [ "Curator" ], "operationId": "getCuratorFanMetrics", "description": "Time-series fan metrics for a curator from a given `source` (one of `spotify`, `facebook`, `twitter`, `youtube_channel`, `instagram`, `tiktok`). Pass `field` to request a single metric (e.g. `followers`, `likes`), or omit it for source defaults: spotify → `followers`; facebook → `followers`, `likes`, `talks`; twitter → `followers`; youtube_channel → `subscribers`, `views`, `videos`; instagram → `followers`; tiktok → `followers`, `likes`.", "parameters": [ { "name": "platform", "in": "path", "schema": { "type": "string", "enum": [ "spotify", "itunes", "applemusic", "deezer" ], "description": "Streaming platform of the curator. Allowed: `spotify`, `itunes`, `applemusic`, `deezer` (`itunes` and `applemusic` return the same data)." }, "required": true, "description": "Streaming platform of the curator. Allowed: `spotify`, `itunes`, `applemusic`, `deezer` (`itunes` and `applemusic` return the same data).", "examples": { "default": { "value": "spotify" } } }, { "name": "id", "in": "path", "schema": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric curator ID." }, "required": true, "description": "Chartmetric curator ID.", "examples": { "default": { "value": 1 } } }, { "name": "source", "in": "path", "schema": { "type": "string", "enum": [ "spotify", "facebook", "twitter", "youtube_channel", "instagram", "tiktok" ], "description": "Social/streaming source for the metric. One of `spotify`, `facebook`, `twitter`, `youtube_channel`, `instagram`, `tiktok`. Pair with `field` to request a single metric." }, "required": true, "description": "Social/streaming source for the metric. One of `spotify`, `facebook`, `twitter`, `youtube_channel`, `instagram`, `tiktok`. Pair with `field` to request a single metric.", "examples": { "default": { "value": "spotify" } } }, { "name": "since", "in": "query", "schema": { "type": "string", "format": "date-time", "description": "Lower bound of the date range in ISO format (e.g. '2024-03-05'). Defaults to 20 days ago. Ignored when `latest=true`.", "default": "2026-10-16" }, "required": false, "description": "Lower bound of the date range in ISO format (e.g. '2024-03-05'). Defaults to 20 days ago. Ignored when `latest=true`." }, { "name": "until", "in": "query", "schema": { "type": "string", "format": "date-time", "description": "Upper bound of the date range in ISO format (e.g. '2024-03-25'). Defaults to today. Ignored when `latest=true`.", "default": "2026-11-05" }, "required": false, "description": "Upper bound of the date range in ISO format (e.g. '2024-03-25'). Defaults to today. Ignored when `latest=true`." }, { "name": "field", "in": "query", "schema": { "type": "string", "description": "Specific stat to return from `source` (e.g. `followers`, `likes`). See the operation description for valid `(source, field)` combinations. If omitted, returns the source defaults." }, "required": false, "description": "Specific stat to return from `source` (e.g. `followers`, `likes`). See the operation description for valid `(source, field)` combinations. If omitted, returns the source defaults." }, { "name": "latest", "in": "query", "schema": { "type": "boolean", "description": "If true, return only the most recent data point and ignore `since`/`until`. Defaults to false.", "default": false }, "required": false, "description": "If true, return only the most recent data point and ignore `since`/`until`. Defaults to false." }, { "name": "interpolated", "in": "query", "schema": { "type": "boolean", "description": "If true, linearly interpolate between adjacent known data points to fill missing days. Each returned point carries an `interpolated` boolean. Defaults to false.", "default": false }, "required": false, "description": "If true, linearly interpolate between adjacent known data points to fill missing days. Each returned point carries an `interpolated` boolean. Defaults to false." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "object", "properties": { "link": { "type": [ "string", "null" ], "description": "URL on `source` associated with the curator (e.g. the curator's Facebook page), when known." }, "followers": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": [ "number", "null" ], "format": "float", "description": "Metric value at this data point." }, "timestp": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO timestamp at which this data point was recorded." }, "flags": { "type": [ "boolean", "null" ], "description": "True if a post was made on `source` on this date (e.g. a Facebook post). Helpful for explaining spikes in nearby metrics." }, "diff": { "type": [ "number", "null" ], "format": "float", "description": "Difference between this data point and the previous one in the array. Always null for the first point." }, "weekly_diff": { "type": [ "number", "null" ], "format": "float", "description": "Difference between `value` today and 7 days ago." }, "weekly_diff_percent": { "type": [ "number", "null" ], "format": "float", "description": "Percentage change in `value` over the past 7 days (e.g. `1.39` means +1.39%)." }, "monthly_diff": { "type": [ "number", "null" ], "format": "float", "description": "Difference between `value` today and 28 days ago." }, "monthly_diff_percent": { "type": [ "number", "null" ], "format": "float", "description": "Percentage change in `value` over the past 28 days (e.g. `1.39` means +1.39%)." }, "daily_diff": { "type": [ "number", "null" ], "format": "float", "description": "Day-over-day difference in `value`. Populated only when `interpolated=true`; when `interpolated=false` the value is returned in `diff` instead. Not applicable for Spotify popularity." }, "interpolated": { "type": [ "boolean", "null" ], "description": "True if this data point was interpolated from neighboring days rather than read from source. Only present when `interpolated=true` was requested." }, "extrapolated": { "type": [ "boolean", "null" ], "description": "True if this data point was extrapolated beyond the available source range." } } }, "description": "Time series of follower counts for this curator on `source`." }, "likes": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": [ "number", "null" ], "format": "float", "description": "Metric value at this data point." }, "timestp": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO timestamp at which this data point was recorded." }, "flags": { "type": [ "boolean", "null" ], "description": "True if a post was made on `source` on this date (e.g. a Facebook post). Helpful for explaining spikes in nearby metrics." }, "diff": { "type": [ "number", "null" ], "format": "float", "description": "Difference between this data point and the previous one in the array. Always null for the first point." }, "weekly_diff": { "type": [ "number", "null" ], "format": "float", "description": "Difference between `value` today and 7 days ago." }, "weekly_diff_percent": { "type": [ "number", "null" ], "format": "float", "description": "Percentage change in `value` over the past 7 days (e.g. `1.39` means +1.39%)." }, "monthly_diff": { "type": [ "number", "null" ], "format": "float", "description": "Difference between `value` today and 28 days ago." }, "monthly_diff_percent": { "type": [ "number", "null" ], "format": "float", "description": "Percentage change in `value` over the past 28 days (e.g. `1.39` means +1.39%)." }, "daily_diff": { "type": [ "number", "null" ], "format": "float", "description": "Day-over-day difference in `value`. Populated only when `interpolated=true`; when `interpolated=false` the value is returned in `diff` instead. Not applicable for Spotify popularity." }, "interpolated": { "type": [ "boolean", "null" ], "description": "True if this data point was interpolated from neighboring days rather than read from source. Only present when `interpolated=true` was requested." }, "extrapolated": { "type": [ "boolean", "null" ], "description": "True if this data point was extrapolated beyond the available source range." } } }, "description": "Time series of cumulative like counts (Facebook, TikTok)." }, "talks": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": [ "number", "null" ], "format": "float", "description": "Metric value at this data point." }, "timestp": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO timestamp at which this data point was recorded." }, "flags": { "type": [ "boolean", "null" ], "description": "True if a post was made on `source` on this date (e.g. a Facebook post). Helpful for explaining spikes in nearby metrics." }, "diff": { "type": [ "number", "null" ], "format": "float", "description": "Difference between this data point and the previous one in the array. Always null for the first point." }, "weekly_diff": { "type": [ "number", "null" ], "format": "float", "description": "Difference between `value` today and 7 days ago." }, "weekly_diff_percent": { "type": [ "number", "null" ], "format": "float", "description": "Percentage change in `value` over the past 7 days (e.g. `1.39` means +1.39%)." }, "monthly_diff": { "type": [ "number", "null" ], "format": "float", "description": "Difference between `value` today and 28 days ago." }, "monthly_diff_percent": { "type": [ "number", "null" ], "format": "float", "description": "Percentage change in `value` over the past 28 days (e.g. `1.39` means +1.39%)." }, "daily_diff": { "type": [ "number", "null" ], "format": "float", "description": "Day-over-day difference in `value`. Populated only when `interpolated=true`; when `interpolated=false` the value is returned in `diff` instead. Not applicable for Spotify popularity." }, "interpolated": { "type": [ "boolean", "null" ], "description": "True if this data point was interpolated from neighboring days rather than read from source. Only present when `interpolated=true` was requested." }, "extrapolated": { "type": [ "boolean", "null" ], "description": "True if this data point was extrapolated beyond the available source range." } } }, "description": "Time series of \"people talking about this\" counts (Facebook)." }, "subscribers": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": [ "number", "null" ], "format": "float", "description": "Metric value at this data point." }, "timestp": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO timestamp at which this data point was recorded." }, "flags": { "type": [ "boolean", "null" ], "description": "True if a post was made on `source` on this date (e.g. a Facebook post). Helpful for explaining spikes in nearby metrics." }, "diff": { "type": [ "number", "null" ], "format": "float", "description": "Difference between this data point and the previous one in the array. Always null for the first point." }, "weekly_diff": { "type": [ "number", "null" ], "format": "float", "description": "Difference between `value` today and 7 days ago." }, "weekly_diff_percent": { "type": [ "number", "null" ], "format": "float", "description": "Percentage change in `value` over the past 7 days (e.g. `1.39` means +1.39%)." }, "monthly_diff": { "type": [ "number", "null" ], "format": "float", "description": "Difference between `value` today and 28 days ago." }, "monthly_diff_percent": { "type": [ "number", "null" ], "format": "float", "description": "Percentage change in `value` over the past 28 days (e.g. `1.39` means +1.39%)." }, "daily_diff": { "type": [ "number", "null" ], "format": "float", "description": "Day-over-day difference in `value`. Populated only when `interpolated=true`; when `interpolated=false` the value is returned in `diff` instead. Not applicable for Spotify popularity." }, "interpolated": { "type": [ "boolean", "null" ], "description": "True if this data point was interpolated from neighboring days rather than read from source. Only present when `interpolated=true` was requested." }, "extrapolated": { "type": [ "boolean", "null" ], "description": "True if this data point was extrapolated beyond the available source range." } } }, "description": "Time series of subscriber counts (YouTube)." }, "views": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": [ "number", "null" ], "format": "float", "description": "Metric value at this data point." }, "timestp": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO timestamp at which this data point was recorded." }, "flags": { "type": [ "boolean", "null" ], "description": "True if a post was made on `source` on this date (e.g. a Facebook post). Helpful for explaining spikes in nearby metrics." }, "diff": { "type": [ "number", "null" ], "format": "float", "description": "Difference between this data point and the previous one in the array. Always null for the first point." }, "weekly_diff": { "type": [ "number", "null" ], "format": "float", "description": "Difference between `value` today and 7 days ago." }, "weekly_diff_percent": { "type": [ "number", "null" ], "format": "float", "description": "Percentage change in `value` over the past 7 days (e.g. `1.39` means +1.39%)." }, "monthly_diff": { "type": [ "number", "null" ], "format": "float", "description": "Difference between `value` today and 28 days ago." }, "monthly_diff_percent": { "type": [ "number", "null" ], "format": "float", "description": "Percentage change in `value` over the past 28 days (e.g. `1.39` means +1.39%)." }, "daily_diff": { "type": [ "number", "null" ], "format": "float", "description": "Day-over-day difference in `value`. Populated only when `interpolated=true`; when `interpolated=false` the value is returned in `diff` instead. Not applicable for Spotify popularity." }, "interpolated": { "type": [ "boolean", "null" ], "description": "True if this data point was interpolated from neighboring days rather than read from source. Only present when `interpolated=true` was requested." }, "extrapolated": { "type": [ "boolean", "null" ], "description": "True if this data point was extrapolated beyond the available source range." } } }, "description": "Time series of cumulative view counts (YouTube)." }, "videos": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": [ "number", "null" ], "format": "float", "description": "Metric value at this data point." }, "timestp": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO timestamp at which this data point was recorded." }, "flags": { "type": [ "boolean", "null" ], "description": "True if a post was made on `source` on this date (e.g. a Facebook post). Helpful for explaining spikes in nearby metrics." }, "diff": { "type": [ "number", "null" ], "format": "float", "description": "Difference between this data point and the previous one in the array. Always null for the first point." }, "weekly_diff": { "type": [ "number", "null" ], "format": "float", "description": "Difference between `value` today and 7 days ago." }, "weekly_diff_percent": { "type": [ "number", "null" ], "format": "float", "description": "Percentage change in `value` over the past 7 days (e.g. `1.39` means +1.39%)." }, "monthly_diff": { "type": [ "number", "null" ], "format": "float", "description": "Difference between `value` today and 28 days ago." }, "monthly_diff_percent": { "type": [ "number", "null" ], "format": "float", "description": "Percentage change in `value` over the past 28 days (e.g. `1.39` means +1.39%)." }, "daily_diff": { "type": [ "number", "null" ], "format": "float", "description": "Day-over-day difference in `value`. Populated only when `interpolated=true`; when `interpolated=false` the value is returned in `diff` instead. Not applicable for Spotify popularity." }, "interpolated": { "type": [ "boolean", "null" ], "description": "True if this data point was interpolated from neighboring days rather than read from source. Only present when `interpolated=true` was requested." }, "extrapolated": { "type": [ "boolean", "null" ], "description": "True if this data point was extrapolated beyond the available source range." } } }, "description": "Time series of cumulative video counts (YouTube)." } } } }, "additionalProperties": false }, "examples": { "default": { "value": { "obj": { "followers": [ { "weekly_diff": null, "weekly_diff_percent": null, "monthly_diff": null, "monthly_diff_percent": null, "value": 462391, "timestp": "2022-02-06T00:00:00.000Z", "flags": false, "diff": null }, { "weekly_diff": null, "weekly_diff_percent": null, "monthly_diff": null, "monthly_diff_percent": null, "value": 464773, "timestp": "2022-02-16T00:00:00.000Z", "flags": false, "diff": 2382 } ] } } } } } } } } } }, "/api/playlist/amazon/lists": { "get": { "summary": "List Amazon Playlists", "tags": [ "Playlist" ], "operationId": "listPlaylistsAmazon", "description": "List amazon playlists with filters (flags, catalogs, tags, moods, activities, etc.), sorting, and pagination. Response shape varies slightly per platform (e.g. Spotify exposes `followers`/`fdiff_*`, YouTube exposes `views`/`vdiff_*`, SoundCloud exposes `latest`/`monthly_diff`). Reach/follower columns may exceed the 32-bit range.", "parameters": [ { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate. `offset + limit` must be ≤ 10,000 (Elasticsearch window)." }, "required": false, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate. `offset + limit` must be ≤ 10,000 (Elasticsearch window)." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 0, "description": "Maximum number of playlists to return per request. Defaults to 50; max 10000. `offset + limit` must be ≤ 10,000.", "default": 50 }, "required": false, "description": "Maximum number of playlists to return per request. Defaults to 50; max 10000. `offset + limit` must be ≤ 10,000." }, { "name": "tagIds[]", "in": "query", "schema": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 2147483647, "title": "genre ID" }, "description": "Filter by Chartmetric genre/tag IDs the playlist is tagged with." }, "required": false, "description": "Filter by Chartmetric genre/tag IDs the playlist is tagged with." }, { "name": "sortColumn", "in": "query", "schema": { "type": "string", "enum": [ "active_ratio", "last_updated", "num_track", "rank" ], "description": "Column to sort playlists by. Allowed values vary per platform; default also varies per platform.", "default": "rank" }, "required": false, "description": "Column to sort playlists by. Allowed values vary per platform; default also varies per platform." }, { "name": "sortOrderDesc", "in": "query", "schema": { "type": "boolean", "description": "If true, sort `sortColumn` in descending order. Defaults to true.", "default": true }, "required": false, "description": "If true, sort `sortColumn` in descending order. Defaults to true." }, { "name": "code2", "in": "query", "schema": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB')." }, "required": false, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB')." }, { "name": "editorial", "in": "query", "schema": { "type": "boolean", "description": "Filter to only editorial playlists curated by the platform (e.g. Spotify-owned). Defaults to true; pass `false` to include user-curated playlists.", "default": true }, "required": false, "description": "Filter to only editorial playlists curated by the platform (e.g. Spotify-owned). Defaults to true; pass `false` to include user-curated playlists." }, { "name": "topPlaylist", "in": "query", "schema": { "type": "boolean", "description": "Filter to only top playlists (high-reach, frequently-updated playlists curated by Chartmetric editors)." }, "required": false, "description": "Filter to only top playlists (high-reach, frequently-updated playlists curated by Chartmetric editors)." }, { "name": "descriptionSearch", "in": "query", "schema": { "type": "string", "description": "Substring match against the playlist description." }, "required": false, "description": "Substring match against the playlist description." }, { "name": "userListIds[]", "in": "query", "schema": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "uniqueItems": true, "description": "Filter by Chartmetric shortlist (user list) IDs the playlist is included on. Public API exposes this as `shortlistIds`." }, "required": false, "description": "Filter by Chartmetric shortlist (user list) IDs the playlist is included on. Public API exposes this as `shortlistIds`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "array", "items": { "type": "object", "properties": { "position": { "type": "integer", "minimum": 0, "description": "Absolute position of the playlist in the result set after filtering and sorting (1-indexed, accounts for `offset`)." }, "id": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "string" } ], "description": "Chartmetric playlist ID. Numeric for Spotify/iTunes/Deezer; string for Amazon (ASIN) and YouTube (channel/playlist ID)." }, "name": { "type": [ "string", "null" ], "description": "Playlist name." }, "image_url": { "type": [ "string", "null" ], "description": "Cover image URL." }, "description": { "type": [ "string", "null" ], "description": "Playlist description as set by the curator." }, "active_ratio": { "type": [ "number", "null" ], "format": "float", "description": "Ratio (0–1) measuring how actively the playlist is being updated." }, "num_track": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "nullable": true, "description": "Total number of tracks currently on the playlist." }, "last_updated": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Date when Chartmetric last observed an update to the playlist." }, "owner_id": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "nullable": true, "description": "Chartmetric curator (owner) ID for the playlist." }, "owner_name": { "type": [ "string", "null" ], "description": "Display name of the playlist owner." }, "code2": { "type": [ "string", "null" ], "description": "Country code associated with the playlist as ISO 3166-1 alpha-2 (e.g. 'US')." }, "editorial": { "type": "boolean", "description": "Whether the playlist is curated by an official editorial team. Applies mainly to Spotify, Apple Music, and Deezer." }, "genre": { "type": [ "string", "null" ], "description": "Comma-separated list of genres associated with the playlist." }, "followers": { "type": [ "integer", "null" ], "minimum": 0, "description": "Current follower/fan count of the playlist (Spotify followers, Deezer fans). May exceed the 32-bit range." }, "fdiff_week": { "type": [ "integer", "null" ], "description": "Difference in followers/likes vs. one week ago (weekly net growth)." }, "fdiff_percent_week": { "type": [ "number", "null" ], "format": "float", "description": "Weekly follower/like growth as a fraction of the prior value (e.g. `0.05` means +5%)." }, "fdiff_month": { "type": [ "integer", "null" ], "description": "Difference in followers/likes vs. one month ago (monthly net growth)." }, "fdiff_percent_month": { "type": [ "number", "null" ], "format": "float", "description": "Monthly follower/like growth as a fraction of the prior value." }, "playlist_id": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "string" } ], "nullable": true, "description": "Platform-native playlist ID (e.g. Spotify URI suffix)." }, "user_id": { "type": [ "string", "null" ], "description": "Platform-native owner/user ID (e.g. Spotify user ID)." }, "catalog": { "type": [ "string", "null" ], "description": "Catalog classification of the playlist tracks (e.g. `frontline`, `catalogue`, `mixed`)." }, "personalized": { "type": "boolean", "description": "Whether the playlist is personalized (varies per listener, e.g. Discover Weekly)." }, "playlist_updated": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Date when the playlist contents (track list) were last changed." }, "tag_ids": { "type": [ "array", "null" ], "items": { "type": "integer", "minimum": 0 }, "description": "Chartmetric tag/genre IDs associated with the playlist." }, "suspicion_score": { "type": [ "number", "null" ], "format": "float", "description": "Score indicating likelihood of suspicious activity on the playlist (0–100). Higher means more suspicious." }, "submithub_url": { "type": [ "string", "null" ], "description": "SubmitHub submission URL for the playlist's curator, if available." }, "groover_url": { "type": [ "string", "null" ], "description": "Groover submission URL for the playlist's curator, if available." }, "score_100": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric's 0–100 quality score for the playlist." }, "views": { "type": [ "integer", "null" ], "minimum": 0, "description": "Current view count of the playlist (YouTube). May exceed the 32-bit range." }, "vdiff_week": { "type": [ "integer", "null" ], "description": "Difference in views vs. one week ago (YouTube)." }, "vdiff_percent_week": { "type": [ "number", "null" ], "format": "float", "description": "Weekly view-count growth as a fraction (YouTube)." }, "vdiff_month": { "type": [ "integer", "null" ], "description": "Difference in views vs. one month ago (YouTube)." }, "vdiff_percent_month": { "type": [ "number", "null" ], "format": "float", "description": "Monthly view-count growth as a fraction (YouTube)." }, "youtube_last_updated": { "anyOf": [ { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Date when the YouTube playlist was last observed updated." }, "permalink": { "type": [ "string", "null" ], "description": "SoundCloud playlist permalink slug." }, "artist_permalink": { "type": [ "string", "null" ], "description": "SoundCloud permalink slug of the playlist's artist/owner." }, "soundcloud_artist_name": { "type": [ "string", "null" ], "description": "Display name of the playlist's artist on SoundCloud." }, "monthly_diff": { "description": "Monthly difference for the platform-specific stat (SoundCloud)." }, "monthly_diff_percent": { "description": "Monthly difference percent for the platform-specific stat (SoundCloud)." }, "latest": { "description": "Latest value of the platform-specific stat (SoundCloud likes)." }, "soundcloud_updated": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Date when the SoundCloud playlist was last observed updated." }, "with_storefronts": { "type": "boolean", "description": "Whether storefront-level data (`code2s`) is attached to this entry (iTunes)." }, "code2s": { "type": "array", "items": { "type": "string" }, "description": "List of ISO 3166-1 alpha-2 storefronts where the playlist is available (iTunes)." }, "chart": { "type": "boolean", "description": "Whether the playlist is a platform chart playlist (e.g. Top 50)." }, "radio": { "type": "boolean", "description": "Whether the playlist is an algorithmic radio-style playlist seeded from a track or artist." }, "music_brand_curator": { "type": "boolean", "description": "Whether the curator is a music-industry brand (label or music publication)." }, "non_music_brand_curator": { "type": "boolean", "description": "Whether the curator is a non-music-industry brand (retailer, media outlet, lifestyle)." }, "editorial_brand": { "type": "boolean", "description": "Whether the playlist is an editorial playlist operated by a brand." }, "indie_curator": { "type": "boolean", "description": "Whether the curator is classified as indie (not editorial / brand / major-label)." }, "personality_artist_curator": { "type": "boolean", "description": "Whether the curator is a personality artist (artist with influence beyond their music)." }, "curator_id": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "string" } ], "nullable": true, "description": "Chartmetric curator ID for the playlist owner." }, "chart_ranks": { "type": "array", "items": {}, "description": "Recent chart-rank history of the playlist on the platform (iTunes)." }, "rank": { "type": [ "integer", "null" ], "description": "Playlist's current rank within Amazon's editorial listing." }, "moods": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 0, "description": "Chartmetric mood ID." }, "name": { "type": [ "string", "null" ], "description": "Mood name (e.g. `Chill`, `Energetic`)." } }, "required": [ "id" ] }, "description": "List of moods associated with the playlist." }, "activities": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 0, "description": "Chartmetric mood ID." }, "name": { "type": [ "string", "null" ], "description": "Mood name (e.g. `Chill`, `Energetic`)." } }, "required": [ "id" ] }, "description": "List of activities associated with the playlist." }, "mood_smart_ordered": { "type": [ "array", "null" ], "items": {}, "description": "Moods sorted by relevance via the smart-ordering algorithm." }, "activity_smart_ordered": { "type": [ "array", "null" ], "items": {}, "description": "Activities sorted by relevance via the smart-ordering algorithm." } }, "required": [ "id" ] }, "description": "List of playlists matching the filters and sort." }, "offset": { "type": "integer", "minimum": 0, "description": "Echo of the request `offset` for client-side pagination tracking." }, "total": { "type": "integer", "minimum": 0, "description": "Total number of playlists matching the filters before `limit`/`offset` are applied." } }, "required": [ "obj", "offset", "total" ], "additionalProperties": false }, "examples": { "default": { "value": { "obj": [ { "position": 1, "id": 1645080, "code2": null, "playlist_id": "37i9dQZF1DXcBWIGoYBM5M", "name": "Today's Top Hits", "image_url": "https://i.scdn.co/image/ab67706f00000003a3b1c73cabef96367d1fc553", "personalized": false, "followers": 27093574, "last_updated": "2020-12-21T06:55:23.752Z", "owner_name": "Spotify", "owner_id": 2, "user_id": "spotify", "editorial": true, "fdiff_week": 15895, "fdiff_percent_week": 0.05866704777, "fdiff_month": 56338, "fdiff_percent_month": 0.2079386057, "catalog": "frontline ", "active_ratio": 1, "genre": "pop, top lists" } ], "offset": 0, "total": 1436332 } } } } } } } } }, "/api/playlist/itunes/lists": { "get": { "summary": "List Itunes Playlists", "tags": [ "Playlist" ], "operationId": "listPlaylistsItunes", "description": "List itunes playlists with filters (flags, catalogs, tags, moods, activities, etc.), sorting, and pagination. Response shape varies slightly per platform (e.g. Spotify exposes `followers`/`fdiff_*`, YouTube exposes `views`/`vdiff_*`, SoundCloud exposes `latest`/`monthly_diff`). Reach/follower columns may exceed the 32-bit range.", "parameters": [ { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate. `offset + limit` must be ≤ 10,000 (Elasticsearch window)." }, "required": false, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate. `offset + limit` must be ≤ 10,000 (Elasticsearch window)." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 0, "description": "Maximum number of playlists to return per request. Defaults to 50; max 10000. `offset + limit` must be ≤ 10,000.", "default": 50 }, "required": false, "description": "Maximum number of playlists to return per request. Defaults to 50; max 10000. `offset + limit` must be ≤ 10,000." }, { "name": "tagIds[]", "in": "query", "schema": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 2147483647, "title": "genre ID" }, "description": "Filter by Chartmetric genre/tag IDs the playlist is tagged with." }, "required": false, "description": "Filter by Chartmetric genre/tag IDs the playlist is tagged with." }, { "name": "curatorIds[]", "in": "query", "schema": { "type": "array", "items": { "type": "string", "title": "curator ID" }, "description": "Filter by platform-native curator (user) IDs that own the playlist (e.g. Spotify user IDs)." }, "required": false, "description": "Filter by platform-native curator (user) IDs that own the playlist (e.g. Spotify user IDs)." }, { "name": "excludedCuratorListIds[]", "in": "query", "schema": { "type": "array", "items": { "type": "string", "title": "exclude curator ID" }, "description": "Exclude playlists owned by these platform-native curator (user) IDs." }, "required": false, "description": "Exclude playlists owned by these platform-native curator (user) IDs." }, { "name": "sortColumn", "in": "query", "schema": { "type": "string", "enum": [ "active_ratio", "num_track", "last_updated" ], "description": "Column to sort playlists by. Allowed values vary per platform; default also varies per platform.", "default": "active_ratio" }, "required": false, "description": "Column to sort playlists by. Allowed values vary per platform; default also varies per platform." }, { "name": "sortOrderDesc", "in": "query", "schema": { "type": "boolean", "description": "If true, sort `sortColumn` in descending order. Defaults to true.", "default": true }, "required": false, "description": "If true, sort `sortColumn` in descending order. Defaults to true." }, { "name": "code2", "in": "query", "schema": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB').", "default": "US" }, "required": false, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB')." }, { "name": "indie", "in": "query", "schema": { "type": "boolean", "description": "Filter to only playlists tagged as indie (independently curated)." }, "required": false, "description": "Filter to only playlists tagged as indie (independently curated)." }, { "name": "editorial", "in": "query", "schema": { "type": "boolean", "description": "Filter to only editorial playlists curated by the platform (e.g. Spotify-owned). Defaults to true; pass `false` to include user-curated playlists.", "default": true }, "required": false, "description": "Filter to only editorial playlists curated by the platform (e.g. Spotify-owned). Defaults to true; pass `false` to include user-curated playlists." }, { "name": "topPlaylist", "in": "query", "schema": { "type": "boolean", "description": "Filter to only top playlists (high-reach, frequently-updated playlists curated by Chartmetric editors)." }, "required": false, "description": "Filter to only top playlists (high-reach, frequently-updated playlists curated by Chartmetric editors)." }, { "name": "descriptionSearch", "in": "query", "schema": { "type": "string", "description": "Substring match against the playlist description." }, "required": false, "description": "Substring match against the playlist description." }, { "name": "userListIds[]", "in": "query", "schema": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "uniqueItems": true, "description": "Filter by Chartmetric shortlist (user list) IDs the playlist is included on. Public API exposes this as `shortlistIds`." }, "required": false, "description": "Filter by Chartmetric shortlist (user list) IDs the playlist is included on. Public API exposes this as `shortlistIds`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "array", "items": { "type": "object", "properties": { "position": { "type": "integer", "minimum": 0, "description": "Absolute position of the playlist in the result set after filtering and sorting (1-indexed, accounts for `offset`)." }, "id": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "string" } ], "description": "Chartmetric playlist ID. Numeric for Spotify/iTunes/Deezer; string for Amazon (ASIN) and YouTube (channel/playlist ID)." }, "name": { "type": [ "string", "null" ], "description": "Playlist name." }, "image_url": { "type": [ "string", "null" ], "description": "Cover image URL." }, "description": { "type": [ "string", "null" ], "description": "Playlist description as set by the curator." }, "active_ratio": { "type": [ "number", "null" ], "format": "float", "description": "Ratio (0–1) measuring how actively the playlist is being updated." }, "num_track": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "nullable": true, "description": "Total number of tracks currently on the playlist." }, "last_updated": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Date when Chartmetric last observed an update to the playlist." }, "owner_id": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "nullable": true, "description": "Chartmetric curator (owner) ID for the playlist." }, "owner_name": { "type": [ "string", "null" ], "description": "Display name of the playlist owner." }, "code2": { "type": [ "string", "null" ], "description": "Country code associated with the playlist as ISO 3166-1 alpha-2 (e.g. 'US')." }, "editorial": { "type": "boolean", "description": "Whether the playlist is curated by an official editorial team. Applies mainly to Spotify, Apple Music, and Deezer." }, "genre": { "type": [ "string", "null" ], "description": "Comma-separated list of genres associated with the playlist." }, "followers": { "type": [ "integer", "null" ], "minimum": 0, "description": "Current follower/fan count of the playlist (Spotify followers, Deezer fans). May exceed the 32-bit range." }, "fdiff_week": { "type": [ "integer", "null" ], "description": "Difference in followers/likes vs. one week ago (weekly net growth)." }, "fdiff_percent_week": { "type": [ "number", "null" ], "format": "float", "description": "Weekly follower/like growth as a fraction of the prior value (e.g. `0.05` means +5%)." }, "fdiff_month": { "type": [ "integer", "null" ], "description": "Difference in followers/likes vs. one month ago (monthly net growth)." }, "fdiff_percent_month": { "type": [ "number", "null" ], "format": "float", "description": "Monthly follower/like growth as a fraction of the prior value." }, "playlist_id": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "string" } ], "nullable": true, "description": "Platform-native playlist ID (e.g. Spotify URI suffix)." }, "user_id": { "type": [ "string", "null" ], "description": "Platform-native owner/user ID (e.g. Spotify user ID)." }, "catalog": { "type": [ "string", "null" ], "description": "Catalog classification of the playlist tracks (e.g. `frontline`, `catalogue`, `mixed`)." }, "personalized": { "type": "boolean", "description": "Whether the playlist is personalized (varies per listener, e.g. Discover Weekly)." }, "playlist_updated": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Date when the playlist contents (track list) were last changed." }, "tag_ids": { "type": [ "array", "null" ], "items": { "type": "integer", "minimum": 0 }, "description": "Chartmetric tag/genre IDs associated with the playlist." }, "suspicion_score": { "type": [ "number", "null" ], "format": "float", "description": "Score indicating likelihood of suspicious activity on the playlist (0–100). Higher means more suspicious." }, "submithub_url": { "type": [ "string", "null" ], "description": "SubmitHub submission URL for the playlist's curator, if available." }, "groover_url": { "type": [ "string", "null" ], "description": "Groover submission URL for the playlist's curator, if available." }, "score_100": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric's 0–100 quality score for the playlist." }, "views": { "type": [ "integer", "null" ], "minimum": 0, "description": "Current view count of the playlist (YouTube). May exceed the 32-bit range." }, "vdiff_week": { "type": [ "integer", "null" ], "description": "Difference in views vs. one week ago (YouTube)." }, "vdiff_percent_week": { "type": [ "number", "null" ], "format": "float", "description": "Weekly view-count growth as a fraction (YouTube)." }, "vdiff_month": { "type": [ "integer", "null" ], "description": "Difference in views vs. one month ago (YouTube)." }, "vdiff_percent_month": { "type": [ "number", "null" ], "format": "float", "description": "Monthly view-count growth as a fraction (YouTube)." }, "youtube_last_updated": { "anyOf": [ { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Date when the YouTube playlist was last observed updated." }, "permalink": { "type": [ "string", "null" ], "description": "SoundCloud playlist permalink slug." }, "artist_permalink": { "type": [ "string", "null" ], "description": "SoundCloud permalink slug of the playlist's artist/owner." }, "soundcloud_artist_name": { "type": [ "string", "null" ], "description": "Display name of the playlist's artist on SoundCloud." }, "monthly_diff": { "description": "Monthly difference for the platform-specific stat (SoundCloud)." }, "monthly_diff_percent": { "description": "Monthly difference percent for the platform-specific stat (SoundCloud)." }, "latest": { "description": "Latest value of the platform-specific stat (SoundCloud likes)." }, "soundcloud_updated": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Date when the SoundCloud playlist was last observed updated." }, "with_storefronts": { "type": "boolean", "description": "Whether storefront-level data (`code2s`) is attached to this entry (iTunes)." }, "code2s": { "type": "array", "items": { "type": "string" }, "description": "List of ISO 3166-1 alpha-2 storefronts where the playlist is available (iTunes)." }, "chart": { "type": "boolean", "description": "Whether the playlist is a platform chart playlist (e.g. Top 50)." }, "radio": { "type": "boolean", "description": "Whether the playlist is an algorithmic radio-style playlist seeded from a track or artist." }, "music_brand_curator": { "type": "boolean", "description": "Whether the curator is a music-industry brand (label or music publication)." }, "non_music_brand_curator": { "type": "boolean", "description": "Whether the curator is a non-music-industry brand (retailer, media outlet, lifestyle)." }, "editorial_brand": { "type": "boolean", "description": "Whether the playlist is an editorial playlist operated by a brand." }, "indie_curator": { "type": "boolean", "description": "Whether the curator is classified as indie (not editorial / brand / major-label)." }, "personality_artist_curator": { "type": "boolean", "description": "Whether the curator is a personality artist (artist with influence beyond their music)." }, "curator_id": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "string" } ], "nullable": true, "description": "Chartmetric curator ID for the playlist owner." }, "chart_ranks": { "type": "array", "items": {}, "description": "Recent chart-rank history of the playlist on the platform (iTunes)." }, "rank": { "type": [ "integer", "null" ], "description": "Playlist's current rank within Amazon's editorial listing." }, "moods": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 0, "description": "Chartmetric mood ID." }, "name": { "type": [ "string", "null" ], "description": "Mood name (e.g. `Chill`, `Energetic`)." } }, "required": [ "id" ] }, "description": "List of moods associated with the playlist." }, "activities": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 0, "description": "Chartmetric mood ID." }, "name": { "type": [ "string", "null" ], "description": "Mood name (e.g. `Chill`, `Energetic`)." } }, "required": [ "id" ] }, "description": "List of activities associated with the playlist." }, "mood_smart_ordered": { "type": [ "array", "null" ], "items": {}, "description": "Moods sorted by relevance via the smart-ordering algorithm." }, "activity_smart_ordered": { "type": [ "array", "null" ], "items": {}, "description": "Activities sorted by relevance via the smart-ordering algorithm." } }, "required": [ "id" ] }, "description": "List of playlists matching the filters and sort." }, "offset": { "type": "integer", "minimum": 0, "description": "Echo of the request `offset` for client-side pagination tracking." }, "total": { "type": "integer", "minimum": 0, "description": "Total number of playlists matching the filters before `limit`/`offset` are applied." } }, "required": [ "obj", "offset", "total" ], "additionalProperties": false }, "examples": { "default": { "value": { "obj": [ { "position": 1, "id": 1645080, "code2": null, "playlist_id": "37i9dQZF1DXcBWIGoYBM5M", "name": "Today's Top Hits", "image_url": "https://i.scdn.co/image/ab67706f00000003a3b1c73cabef96367d1fc553", "personalized": false, "followers": 27093574, "last_updated": "2020-12-21T06:55:23.752Z", "owner_name": "Spotify", "owner_id": 2, "user_id": "spotify", "editorial": true, "fdiff_week": 15895, "fdiff_percent_week": 0.05866704777, "fdiff_month": 56338, "fdiff_percent_month": 0.2079386057, "catalog": "frontline ", "active_ratio": 1, "genre": "pop, top lists" } ], "offset": 0, "total": 1436332 } } } } } } } } }, "/api/playlist/deezer/lists": { "get": { "summary": "List Deezer Playlists", "tags": [ "Playlist" ], "operationId": "listPlaylistsDeezer", "description": "List deezer playlists with filters (flags, catalogs, tags, moods, activities, etc.), sorting, and pagination. Response shape varies slightly per platform (e.g. Spotify exposes `followers`/`fdiff_*`, YouTube exposes `views`/`vdiff_*`, SoundCloud exposes `latest`/`monthly_diff`). Reach/follower columns may exceed the 32-bit range.", "parameters": [ { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate. `offset + limit` must be ≤ 10,000 (Elasticsearch window)." }, "required": false, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate. `offset + limit` must be ≤ 10,000 (Elasticsearch window)." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 0, "description": "Maximum number of playlists to return per request. Defaults to 50; max 10000. `offset + limit` must be ≤ 10,000.", "default": 50 }, "required": false, "description": "Maximum number of playlists to return per request. Defaults to 50; max 10000. `offset + limit` must be ≤ 10,000." }, { "name": "tagIds[]", "in": "query", "schema": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 2147483647, "title": "genre ID" }, "description": "Filter by Chartmetric genre/tag IDs the playlist is tagged with." }, "required": false, "description": "Filter by Chartmetric genre/tag IDs the playlist is tagged with." }, { "name": "curatorIds[]", "in": "query", "schema": { "type": "array", "items": { "type": "string", "title": "curator ID" }, "description": "Filter by platform-native curator (user) IDs that own the playlist (e.g. Spotify user IDs)." }, "required": false, "description": "Filter by platform-native curator (user) IDs that own the playlist (e.g. Spotify user IDs)." }, { "name": "excludedCuratorListIds[]", "in": "query", "schema": { "type": "array", "items": { "type": "string", "title": "exclude curator ID" }, "description": "Exclude playlists owned by these platform-native curator (user) IDs." }, "required": false, "description": "Exclude playlists owned by these platform-native curator (user) IDs." }, { "name": "sortColumn", "in": "query", "schema": { "type": "string", "enum": [ "active_ratio", "fdiff_month", "fdiff_percent_month", "fdiff_percent_week", "fdiff_week", "followers", "last_updated", "num_track" ], "description": "Column to sort playlists by. Allowed values vary per platform; default also varies per platform.", "default": "followers" }, "required": false, "description": "Column to sort playlists by. Allowed values vary per platform; default also varies per platform." }, { "name": "sortOrderDesc", "in": "query", "schema": { "type": "boolean", "description": "If true, sort `sortColumn` in descending order. Defaults to true.", "default": true }, "required": false, "description": "If true, sort `sortColumn` in descending order. Defaults to true." }, { "name": "code2", "in": "query", "schema": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB')." }, "required": false, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB')." }, { "name": "indie", "in": "query", "schema": { "type": "boolean", "description": "Filter to only playlists tagged as indie (independently curated)." }, "required": false, "description": "Filter to only playlists tagged as indie (independently curated)." }, { "name": "editorial", "in": "query", "schema": { "type": "boolean", "description": "Filter to only editorial playlists curated by the platform (e.g. Spotify-owned). Defaults to true; pass `false` to include user-curated playlists.", "default": true }, "required": false, "description": "Filter to only editorial playlists curated by the platform (e.g. Spotify-owned). Defaults to true; pass `false` to include user-curated playlists." }, { "name": "majorCurator", "in": "query", "schema": { "type": "boolean", "description": "Filter to only playlists owned by a major-label curator (Sony, Universal, Warner, etc.)." }, "required": false, "description": "Filter to only playlists owned by a major-label curator (Sony, Universal, Warner, etc.)." }, { "name": "topPlaylist", "in": "query", "schema": { "type": "boolean", "description": "Filter to only top playlists (high-reach, frequently-updated playlists curated by Chartmetric editors)." }, "required": false, "description": "Filter to only top playlists (high-reach, frequently-updated playlists curated by Chartmetric editors)." }, { "name": "descriptionSearch", "in": "query", "schema": { "type": "string", "description": "Substring match against the playlist description." }, "required": false, "description": "Substring match against the playlist description." }, { "name": "userListIds[]", "in": "query", "schema": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "uniqueItems": true, "description": "Filter by Chartmetric shortlist (user list) IDs the playlist is included on. Public API exposes this as `shortlistIds`." }, "required": false, "description": "Filter by Chartmetric shortlist (user list) IDs the playlist is included on. Public API exposes this as `shortlistIds`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "array", "items": { "type": "object", "properties": { "position": { "type": "integer", "minimum": 0, "description": "Absolute position of the playlist in the result set after filtering and sorting (1-indexed, accounts for `offset`)." }, "id": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "string" } ], "description": "Chartmetric playlist ID. Numeric for Spotify/iTunes/Deezer; string for Amazon (ASIN) and YouTube (channel/playlist ID)." }, "name": { "type": [ "string", "null" ], "description": "Playlist name." }, "image_url": { "type": [ "string", "null" ], "description": "Cover image URL." }, "description": { "type": [ "string", "null" ], "description": "Playlist description as set by the curator." }, "active_ratio": { "type": [ "number", "null" ], "format": "float", "description": "Ratio (0–1) measuring how actively the playlist is being updated." }, "num_track": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "nullable": true, "description": "Total number of tracks currently on the playlist." }, "last_updated": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Date when Chartmetric last observed an update to the playlist." }, "owner_id": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "nullable": true, "description": "Chartmetric curator (owner) ID for the playlist." }, "owner_name": { "type": [ "string", "null" ], "description": "Display name of the playlist owner." }, "code2": { "type": [ "string", "null" ], "description": "Country code associated with the playlist as ISO 3166-1 alpha-2 (e.g. 'US')." }, "editorial": { "type": "boolean", "description": "Whether the playlist is curated by an official editorial team. Applies mainly to Spotify, Apple Music, and Deezer." }, "genre": { "type": [ "string", "null" ], "description": "Comma-separated list of genres associated with the playlist." }, "followers": { "type": [ "integer", "null" ], "minimum": 0, "description": "Current follower/fan count of the playlist (Spotify followers, Deezer fans). May exceed the 32-bit range." }, "fdiff_week": { "type": [ "integer", "null" ], "description": "Difference in followers/likes vs. one week ago (weekly net growth)." }, "fdiff_percent_week": { "type": [ "number", "null" ], "format": "float", "description": "Weekly follower/like growth as a fraction of the prior value (e.g. `0.05` means +5%)." }, "fdiff_month": { "type": [ "integer", "null" ], "description": "Difference in followers/likes vs. one month ago (monthly net growth)." }, "fdiff_percent_month": { "type": [ "number", "null" ], "format": "float", "description": "Monthly follower/like growth as a fraction of the prior value." }, "playlist_id": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "string" } ], "nullable": true, "description": "Platform-native playlist ID (e.g. Spotify URI suffix)." }, "user_id": { "type": [ "string", "null" ], "description": "Platform-native owner/user ID (e.g. Spotify user ID)." }, "catalog": { "type": [ "string", "null" ], "description": "Catalog classification of the playlist tracks (e.g. `frontline`, `catalogue`, `mixed`)." }, "personalized": { "type": "boolean", "description": "Whether the playlist is personalized (varies per listener, e.g. Discover Weekly)." }, "playlist_updated": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Date when the playlist contents (track list) were last changed." }, "tag_ids": { "type": [ "array", "null" ], "items": { "type": "integer", "minimum": 0 }, "description": "Chartmetric tag/genre IDs associated with the playlist." }, "suspicion_score": { "type": [ "number", "null" ], "format": "float", "description": "Score indicating likelihood of suspicious activity on the playlist (0–100). Higher means more suspicious." }, "submithub_url": { "type": [ "string", "null" ], "description": "SubmitHub submission URL for the playlist's curator, if available." }, "groover_url": { "type": [ "string", "null" ], "description": "Groover submission URL for the playlist's curator, if available." }, "score_100": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric's 0–100 quality score for the playlist." }, "views": { "type": [ "integer", "null" ], "minimum": 0, "description": "Current view count of the playlist (YouTube). May exceed the 32-bit range." }, "vdiff_week": { "type": [ "integer", "null" ], "description": "Difference in views vs. one week ago (YouTube)." }, "vdiff_percent_week": { "type": [ "number", "null" ], "format": "float", "description": "Weekly view-count growth as a fraction (YouTube)." }, "vdiff_month": { "type": [ "integer", "null" ], "description": "Difference in views vs. one month ago (YouTube)." }, "vdiff_percent_month": { "type": [ "number", "null" ], "format": "float", "description": "Monthly view-count growth as a fraction (YouTube)." }, "youtube_last_updated": { "anyOf": [ { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Date when the YouTube playlist was last observed updated." }, "permalink": { "type": [ "string", "null" ], "description": "SoundCloud playlist permalink slug." }, "artist_permalink": { "type": [ "string", "null" ], "description": "SoundCloud permalink slug of the playlist's artist/owner." }, "soundcloud_artist_name": { "type": [ "string", "null" ], "description": "Display name of the playlist's artist on SoundCloud." }, "monthly_diff": { "description": "Monthly difference for the platform-specific stat (SoundCloud)." }, "monthly_diff_percent": { "description": "Monthly difference percent for the platform-specific stat (SoundCloud)." }, "latest": { "description": "Latest value of the platform-specific stat (SoundCloud likes)." }, "soundcloud_updated": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Date when the SoundCloud playlist was last observed updated." }, "with_storefronts": { "type": "boolean", "description": "Whether storefront-level data (`code2s`) is attached to this entry (iTunes)." }, "code2s": { "type": "array", "items": { "type": "string" }, "description": "List of ISO 3166-1 alpha-2 storefronts where the playlist is available (iTunes)." }, "chart": { "type": "boolean", "description": "Whether the playlist is a platform chart playlist (e.g. Top 50)." }, "radio": { "type": "boolean", "description": "Whether the playlist is an algorithmic radio-style playlist seeded from a track or artist." }, "music_brand_curator": { "type": "boolean", "description": "Whether the curator is a music-industry brand (label or music publication)." }, "non_music_brand_curator": { "type": "boolean", "description": "Whether the curator is a non-music-industry brand (retailer, media outlet, lifestyle)." }, "editorial_brand": { "type": "boolean", "description": "Whether the playlist is an editorial playlist operated by a brand." }, "indie_curator": { "type": "boolean", "description": "Whether the curator is classified as indie (not editorial / brand / major-label)." }, "personality_artist_curator": { "type": "boolean", "description": "Whether the curator is a personality artist (artist with influence beyond their music)." }, "curator_id": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "string" } ], "nullable": true, "description": "Chartmetric curator ID for the playlist owner." }, "chart_ranks": { "type": "array", "items": {}, "description": "Recent chart-rank history of the playlist on the platform (iTunes)." }, "rank": { "type": [ "integer", "null" ], "description": "Playlist's current rank within Amazon's editorial listing." }, "moods": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 0, "description": "Chartmetric mood ID." }, "name": { "type": [ "string", "null" ], "description": "Mood name (e.g. `Chill`, `Energetic`)." } }, "required": [ "id" ] }, "description": "List of moods associated with the playlist." }, "activities": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 0, "description": "Chartmetric mood ID." }, "name": { "type": [ "string", "null" ], "description": "Mood name (e.g. `Chill`, `Energetic`)." } }, "required": [ "id" ] }, "description": "List of activities associated with the playlist." }, "mood_smart_ordered": { "type": [ "array", "null" ], "items": {}, "description": "Moods sorted by relevance via the smart-ordering algorithm." }, "activity_smart_ordered": { "type": [ "array", "null" ], "items": {}, "description": "Activities sorted by relevance via the smart-ordering algorithm." } }, "required": [ "id" ] }, "description": "List of playlists matching the filters and sort." }, "offset": { "type": "integer", "minimum": 0, "description": "Echo of the request `offset` for client-side pagination tracking." }, "total": { "type": "integer", "minimum": 0, "description": "Total number of playlists matching the filters before `limit`/`offset` are applied." } }, "required": [ "obj", "offset", "total" ], "additionalProperties": false }, "examples": { "default": { "value": { "obj": [ { "position": 1, "id": 1645080, "code2": null, "playlist_id": "37i9dQZF1DXcBWIGoYBM5M", "name": "Today's Top Hits", "image_url": "https://i.scdn.co/image/ab67706f00000003a3b1c73cabef96367d1fc553", "personalized": false, "followers": 27093574, "last_updated": "2020-12-21T06:55:23.752Z", "owner_name": "Spotify", "owner_id": 2, "user_id": "spotify", "editorial": true, "fdiff_week": 15895, "fdiff_percent_week": 0.05866704777, "fdiff_month": 56338, "fdiff_percent_month": 0.2079386057, "catalog": "frontline ", "active_ratio": 1, "genre": "pop, top lists" } ], "offset": 0, "total": 1436332 } } } } } } } } }, "/api/playlist/spotify/lists": { "get": { "summary": "List Spotify Playlists", "tags": [ "Playlist" ], "operationId": "listPlaylistsSpotify", "description": "List spotify playlists with filters (flags, catalogs, tags, moods, activities, etc.), sorting, and pagination. Response shape varies slightly per platform (e.g. Spotify exposes `followers`/`fdiff_*`, YouTube exposes `views`/`vdiff_*`, SoundCloud exposes `latest`/`monthly_diff`). Reach/follower columns may exceed the 32-bit range.", "parameters": [ { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate. `offset + limit` must be ≤ 10,000 (Elasticsearch window)." }, "required": false, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate. `offset + limit` must be ≤ 10,000 (Elasticsearch window)." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 0, "description": "Maximum number of playlists to return per request. Defaults to 50; max 10000. `offset + limit` must be ≤ 10,000.", "default": 50 }, "required": false, "description": "Maximum number of playlists to return per request. Defaults to 50; max 10000. `offset + limit` must be ≤ 10,000." }, { "name": "tagIds[]", "in": "query", "schema": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 2147483647, "title": "genre ID" }, "description": "Filter by Chartmetric genre/tag IDs the playlist is tagged with." }, "required": false, "description": "Filter by Chartmetric genre/tag IDs the playlist is tagged with." }, { "name": "curatorIds[]", "in": "query", "schema": { "type": "array", "items": { "type": "string", "title": "curator ID" }, "description": "Filter by platform-native curator (user) IDs that own the playlist (e.g. Spotify user IDs)." }, "required": false, "description": "Filter by platform-native curator (user) IDs that own the playlist (e.g. Spotify user IDs)." }, { "name": "excludedCuratorListIds[]", "in": "query", "schema": { "type": "array", "items": { "type": "string", "title": "exclude curator ID" }, "description": "Exclude playlists owned by these platform-native curator (user) IDs." }, "required": false, "description": "Exclude playlists owned by these platform-native curator (user) IDs." }, { "name": "sortColumn", "in": "query", "schema": { "type": "string", "enum": [ "active_ratio", "fdiff_month", "fdiff_percent_month", "fdiff_percent_week", "fdiff_week", "followers", "last_updated", "num_track", "playlist_updated", "score_100" ], "description": "Column to sort playlists by. Allowed values vary per platform; default also varies per platform.", "default": "followers" }, "required": false, "description": "Column to sort playlists by. Allowed values vary per platform; default also varies per platform." }, { "name": "sortOrderDesc", "in": "query", "schema": { "type": "boolean", "description": "If true, sort `sortColumn` in descending order. Defaults to true.", "default": true }, "required": false, "description": "If true, sort `sortColumn` in descending order. Defaults to true." }, { "name": "code2", "in": "query", "schema": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB')." }, "required": false, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB')." }, { "name": "indie", "in": "query", "schema": { "type": "boolean", "description": "Filter to only playlists tagged as indie (independently curated)." }, "required": false, "description": "Filter to only playlists tagged as indie (independently curated)." }, { "name": "editorial", "in": "query", "schema": { "type": "boolean", "description": "Filter to only editorial playlists curated by the platform (e.g. Spotify-owned). Defaults to true; pass `false` to include user-curated playlists.", "default": true }, "required": false, "description": "Filter to only editorial playlists curated by the platform (e.g. Spotify-owned). Defaults to true; pass `false` to include user-curated playlists." }, { "name": "majorCurator", "in": "query", "schema": { "type": "boolean", "description": "Filter to only playlists owned by a major-label curator (Sony, Universal, Warner, etc.)." }, "required": false, "description": "Filter to only playlists owned by a major-label curator (Sony, Universal, Warner, etc.)." }, { "name": "newMusicFriday", "in": "query", "schema": { "type": "boolean", "description": "Filter to only New Music Friday-style new-release playlists." }, "required": false, "description": "Filter to only New Music Friday-style new-release playlists." }, { "name": "topPlaylist", "in": "query", "schema": { "type": "boolean", "description": "Filter to only top playlists (high-reach, frequently-updated playlists curated by Chartmetric editors)." }, "required": false, "description": "Filter to only top playlists (high-reach, frequently-updated playlists curated by Chartmetric editors)." }, { "name": "descriptionSearch", "in": "query", "schema": { "type": "string", "description": "Substring match against the playlist description." }, "required": false, "description": "Substring match against the playlist description." }, { "name": "userListIds[]", "in": "query", "schema": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "uniqueItems": true, "description": "Filter by Chartmetric shortlist (user list) IDs the playlist is included on. Public API exposes this as `shortlistIds`." }, "required": false, "description": "Filter by Chartmetric shortlist (user list) IDs the playlist is included on. Public API exposes this as `shortlistIds`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "array", "items": { "type": "object", "properties": { "position": { "type": "integer", "minimum": 0, "description": "Absolute position of the playlist in the result set after filtering and sorting (1-indexed, accounts for `offset`)." }, "id": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "string" } ], "description": "Chartmetric playlist ID. Numeric for Spotify/iTunes/Deezer; string for Amazon (ASIN) and YouTube (channel/playlist ID)." }, "name": { "type": [ "string", "null" ], "description": "Playlist name." }, "image_url": { "type": [ "string", "null" ], "description": "Cover image URL." }, "description": { "type": [ "string", "null" ], "description": "Playlist description as set by the curator." }, "active_ratio": { "type": [ "number", "null" ], "format": "float", "description": "Ratio (0–1) measuring how actively the playlist is being updated." }, "num_track": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "nullable": true, "description": "Total number of tracks currently on the playlist." }, "last_updated": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Date when Chartmetric last observed an update to the playlist." }, "owner_id": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "nullable": true, "description": "Chartmetric curator (owner) ID for the playlist." }, "owner_name": { "type": [ "string", "null" ], "description": "Display name of the playlist owner." }, "code2": { "type": [ "string", "null" ], "description": "Country code associated with the playlist as ISO 3166-1 alpha-2 (e.g. 'US')." }, "editorial": { "type": "boolean", "description": "Whether the playlist is curated by an official editorial team. Applies mainly to Spotify, Apple Music, and Deezer." }, "genre": { "type": [ "string", "null" ], "description": "Comma-separated list of genres associated with the playlist." }, "followers": { "type": [ "integer", "null" ], "minimum": 0, "description": "Current follower/fan count of the playlist (Spotify followers, Deezer fans). May exceed the 32-bit range." }, "fdiff_week": { "type": [ "integer", "null" ], "description": "Difference in followers/likes vs. one week ago (weekly net growth)." }, "fdiff_percent_week": { "type": [ "number", "null" ], "format": "float", "description": "Weekly follower/like growth as a fraction of the prior value (e.g. `0.05` means +5%)." }, "fdiff_month": { "type": [ "integer", "null" ], "description": "Difference in followers/likes vs. one month ago (monthly net growth)." }, "fdiff_percent_month": { "type": [ "number", "null" ], "format": "float", "description": "Monthly follower/like growth as a fraction of the prior value." }, "playlist_id": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "string" } ], "nullable": true, "description": "Platform-native playlist ID (e.g. Spotify URI suffix)." }, "user_id": { "type": [ "string", "null" ], "description": "Platform-native owner/user ID (e.g. Spotify user ID)." }, "catalog": { "type": [ "string", "null" ], "description": "Catalog classification of the playlist tracks (e.g. `frontline`, `catalogue`, `mixed`)." }, "personalized": { "type": "boolean", "description": "Whether the playlist is personalized (varies per listener, e.g. Discover Weekly)." }, "playlist_updated": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Date when the playlist contents (track list) were last changed." }, "tag_ids": { "type": [ "array", "null" ], "items": { "type": "integer", "minimum": 0 }, "description": "Chartmetric tag/genre IDs associated with the playlist." }, "suspicion_score": { "type": [ "number", "null" ], "format": "float", "description": "Score indicating likelihood of suspicious activity on the playlist (0–100). Higher means more suspicious." }, "submithub_url": { "type": [ "string", "null" ], "description": "SubmitHub submission URL for the playlist's curator, if available." }, "groover_url": { "type": [ "string", "null" ], "description": "Groover submission URL for the playlist's curator, if available." }, "score_100": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric's 0–100 quality score for the playlist." }, "views": { "type": [ "integer", "null" ], "minimum": 0, "description": "Current view count of the playlist (YouTube). May exceed the 32-bit range." }, "vdiff_week": { "type": [ "integer", "null" ], "description": "Difference in views vs. one week ago (YouTube)." }, "vdiff_percent_week": { "type": [ "number", "null" ], "format": "float", "description": "Weekly view-count growth as a fraction (YouTube)." }, "vdiff_month": { "type": [ "integer", "null" ], "description": "Difference in views vs. one month ago (YouTube)." }, "vdiff_percent_month": { "type": [ "number", "null" ], "format": "float", "description": "Monthly view-count growth as a fraction (YouTube)." }, "youtube_last_updated": { "anyOf": [ { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Date when the YouTube playlist was last observed updated." }, "permalink": { "type": [ "string", "null" ], "description": "SoundCloud playlist permalink slug." }, "artist_permalink": { "type": [ "string", "null" ], "description": "SoundCloud permalink slug of the playlist's artist/owner." }, "soundcloud_artist_name": { "type": [ "string", "null" ], "description": "Display name of the playlist's artist on SoundCloud." }, "monthly_diff": { "description": "Monthly difference for the platform-specific stat (SoundCloud)." }, "monthly_diff_percent": { "description": "Monthly difference percent for the platform-specific stat (SoundCloud)." }, "latest": { "description": "Latest value of the platform-specific stat (SoundCloud likes)." }, "soundcloud_updated": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Date when the SoundCloud playlist was last observed updated." }, "with_storefronts": { "type": "boolean", "description": "Whether storefront-level data (`code2s`) is attached to this entry (iTunes)." }, "code2s": { "type": "array", "items": { "type": "string" }, "description": "List of ISO 3166-1 alpha-2 storefronts where the playlist is available (iTunes)." }, "chart": { "type": "boolean", "description": "Whether the playlist is a platform chart playlist (e.g. Top 50)." }, "radio": { "type": "boolean", "description": "Whether the playlist is an algorithmic radio-style playlist seeded from a track or artist." }, "music_brand_curator": { "type": "boolean", "description": "Whether the curator is a music-industry brand (label or music publication)." }, "non_music_brand_curator": { "type": "boolean", "description": "Whether the curator is a non-music-industry brand (retailer, media outlet, lifestyle)." }, "editorial_brand": { "type": "boolean", "description": "Whether the playlist is an editorial playlist operated by a brand." }, "indie_curator": { "type": "boolean", "description": "Whether the curator is classified as indie (not editorial / brand / major-label)." }, "personality_artist_curator": { "type": "boolean", "description": "Whether the curator is a personality artist (artist with influence beyond their music)." }, "curator_id": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "string" } ], "nullable": true, "description": "Chartmetric curator ID for the playlist owner." }, "chart_ranks": { "type": "array", "items": {}, "description": "Recent chart-rank history of the playlist on the platform (iTunes)." }, "rank": { "type": [ "integer", "null" ], "description": "Playlist's current rank within Amazon's editorial listing." }, "moods": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 0, "description": "Chartmetric mood ID." }, "name": { "type": [ "string", "null" ], "description": "Mood name (e.g. `Chill`, `Energetic`)." } }, "required": [ "id" ] }, "description": "List of moods associated with the playlist." }, "activities": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 0, "description": "Chartmetric mood ID." }, "name": { "type": [ "string", "null" ], "description": "Mood name (e.g. `Chill`, `Energetic`)." } }, "required": [ "id" ] }, "description": "List of activities associated with the playlist." }, "mood_smart_ordered": { "type": [ "array", "null" ], "items": {}, "description": "Moods sorted by relevance via the smart-ordering algorithm." }, "activity_smart_ordered": { "type": [ "array", "null" ], "items": {}, "description": "Activities sorted by relevance via the smart-ordering algorithm." } }, "required": [ "id" ] }, "description": "List of playlists matching the filters and sort." }, "offset": { "type": "integer", "minimum": 0, "description": "Echo of the request `offset` for client-side pagination tracking." }, "total": { "type": "integer", "minimum": 0, "description": "Total number of playlists matching the filters before `limit`/`offset` are applied." } }, "required": [ "obj", "offset", "total" ], "additionalProperties": false }, "examples": { "default": { "value": { "obj": [ { "position": 1, "id": 1645080, "code2": null, "playlist_id": "37i9dQZF1DXcBWIGoYBM5M", "name": "Today's Top Hits", "image_url": "https://i.scdn.co/image/ab67706f00000003a3b1c73cabef96367d1fc553", "personalized": false, "followers": 27093574, "last_updated": "2020-12-21T06:55:23.752Z", "owner_name": "Spotify", "owner_id": 2, "user_id": "spotify", "editorial": true, "fdiff_week": 15895, "fdiff_percent_week": 0.05866704777, "fdiff_month": 56338, "fdiff_percent_month": 0.2079386057, "catalog": "frontline ", "active_ratio": 1, "genre": "pop, top lists" } ], "offset": 0, "total": 1436332 } } } } } } } } }, "/api/playlist/youtube/lists": { "get": { "summary": "List Youtube Playlists", "tags": [ "Playlist" ], "operationId": "listPlaylistsYoutube", "description": "List youtube playlists with filters (flags, catalogs, tags, moods, activities, etc.), sorting, and pagination. Response shape varies slightly per platform (e.g. Spotify exposes `followers`/`fdiff_*`, YouTube exposes `views`/`vdiff_*`, SoundCloud exposes `latest`/`monthly_diff`). Reach/follower columns may exceed the 32-bit range.", "parameters": [ { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate. `offset + limit` must be ≤ 10,000 (Elasticsearch window)." }, "required": false, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate. `offset + limit` must be ≤ 10,000 (Elasticsearch window)." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 0, "description": "Maximum number of playlists to return per request. Defaults to 50; max 10000. `offset + limit` must be ≤ 10,000.", "default": 50 }, "required": false, "description": "Maximum number of playlists to return per request. Defaults to 50; max 10000. `offset + limit` must be ≤ 10,000." }, { "name": "tagIds[]", "in": "query", "schema": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 2147483647, "title": "genre ID" }, "description": "Filter by Chartmetric genre/tag IDs the playlist is tagged with." }, "required": false, "description": "Filter by Chartmetric genre/tag IDs the playlist is tagged with." }, { "name": "sortColumn", "in": "query", "schema": { "type": "string", "enum": [ "active_ratio", "last_updated", "num_track", "vdiff_month", "vdiff_percent_month", "vdiff_percent_week", "vdiff_week", "views" ], "description": "Column to sort playlists by. Allowed values vary per platform; default also varies per platform.", "default": "views" }, "required": false, "description": "Column to sort playlists by. Allowed values vary per platform; default also varies per platform." }, { "name": "sortOrderDesc", "in": "query", "schema": { "type": "boolean", "description": "If true, sort `sortColumn` in descending order. Defaults to true.", "default": true }, "required": false, "description": "If true, sort `sortColumn` in descending order. Defaults to true." }, { "name": "indie", "in": "query", "schema": { "type": "boolean", "description": "Filter to only playlists tagged as indie (independently curated)." }, "required": false, "description": "Filter to only playlists tagged as indie (independently curated)." }, { "name": "editorial", "in": "query", "schema": { "type": "boolean", "description": "Filter to only editorial playlists curated by the platform (e.g. Spotify-owned). Defaults to true; pass `false` to include user-curated playlists.", "default": true }, "required": false, "description": "Filter to only editorial playlists curated by the platform (e.g. Spotify-owned). Defaults to true; pass `false` to include user-curated playlists." }, { "name": "topPlaylist", "in": "query", "schema": { "type": "boolean", "description": "Filter to only top playlists (high-reach, frequently-updated playlists curated by Chartmetric editors)." }, "required": false, "description": "Filter to only top playlists (high-reach, frequently-updated playlists curated by Chartmetric editors)." }, { "name": "descriptionSearch", "in": "query", "schema": { "type": "string", "description": "Substring match against the playlist description." }, "required": false, "description": "Substring match against the playlist description." }, { "name": "userListIds[]", "in": "query", "schema": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "uniqueItems": true, "description": "Filter by Chartmetric shortlist (user list) IDs the playlist is included on. Public API exposes this as `shortlistIds`." }, "required": false, "description": "Filter by Chartmetric shortlist (user list) IDs the playlist is included on. Public API exposes this as `shortlistIds`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "array", "items": { "type": "object", "properties": { "position": { "type": "integer", "minimum": 0, "description": "Absolute position of the playlist in the result set after filtering and sorting (1-indexed, accounts for `offset`)." }, "id": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "string" } ], "description": "Chartmetric playlist ID. Numeric for Spotify/iTunes/Deezer; string for Amazon (ASIN) and YouTube (channel/playlist ID)." }, "name": { "type": [ "string", "null" ], "description": "Playlist name." }, "image_url": { "type": [ "string", "null" ], "description": "Cover image URL." }, "description": { "type": [ "string", "null" ], "description": "Playlist description as set by the curator." }, "active_ratio": { "type": [ "number", "null" ], "format": "float", "description": "Ratio (0–1) measuring how actively the playlist is being updated." }, "num_track": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "nullable": true, "description": "Total number of tracks currently on the playlist." }, "last_updated": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Date when Chartmetric last observed an update to the playlist." }, "owner_id": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "nullable": true, "description": "Chartmetric curator (owner) ID for the playlist." }, "owner_name": { "type": [ "string", "null" ], "description": "Display name of the playlist owner." }, "code2": { "type": [ "string", "null" ], "description": "Country code associated with the playlist as ISO 3166-1 alpha-2 (e.g. 'US')." }, "editorial": { "type": "boolean", "description": "Whether the playlist is curated by an official editorial team. Applies mainly to Spotify, Apple Music, and Deezer." }, "genre": { "type": [ "string", "null" ], "description": "Comma-separated list of genres associated with the playlist." }, "followers": { "type": [ "integer", "null" ], "minimum": 0, "description": "Current follower/fan count of the playlist (Spotify followers, Deezer fans). May exceed the 32-bit range." }, "fdiff_week": { "type": [ "integer", "null" ], "description": "Difference in followers/likes vs. one week ago (weekly net growth)." }, "fdiff_percent_week": { "type": [ "number", "null" ], "format": "float", "description": "Weekly follower/like growth as a fraction of the prior value (e.g. `0.05` means +5%)." }, "fdiff_month": { "type": [ "integer", "null" ], "description": "Difference in followers/likes vs. one month ago (monthly net growth)." }, "fdiff_percent_month": { "type": [ "number", "null" ], "format": "float", "description": "Monthly follower/like growth as a fraction of the prior value." }, "playlist_id": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "string" } ], "nullable": true, "description": "Platform-native playlist ID (e.g. Spotify URI suffix)." }, "user_id": { "type": [ "string", "null" ], "description": "Platform-native owner/user ID (e.g. Spotify user ID)." }, "catalog": { "type": [ "string", "null" ], "description": "Catalog classification of the playlist tracks (e.g. `frontline`, `catalogue`, `mixed`)." }, "personalized": { "type": "boolean", "description": "Whether the playlist is personalized (varies per listener, e.g. Discover Weekly)." }, "playlist_updated": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Date when the playlist contents (track list) were last changed." }, "tag_ids": { "type": [ "array", "null" ], "items": { "type": "integer", "minimum": 0 }, "description": "Chartmetric tag/genre IDs associated with the playlist." }, "suspicion_score": { "type": [ "number", "null" ], "format": "float", "description": "Score indicating likelihood of suspicious activity on the playlist (0–100). Higher means more suspicious." }, "submithub_url": { "type": [ "string", "null" ], "description": "SubmitHub submission URL for the playlist's curator, if available." }, "groover_url": { "type": [ "string", "null" ], "description": "Groover submission URL for the playlist's curator, if available." }, "score_100": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric's 0–100 quality score for the playlist." }, "views": { "type": [ "integer", "null" ], "minimum": 0, "description": "Current view count of the playlist (YouTube). May exceed the 32-bit range." }, "vdiff_week": { "type": [ "integer", "null" ], "description": "Difference in views vs. one week ago (YouTube)." }, "vdiff_percent_week": { "type": [ "number", "null" ], "format": "float", "description": "Weekly view-count growth as a fraction (YouTube)." }, "vdiff_month": { "type": [ "integer", "null" ], "description": "Difference in views vs. one month ago (YouTube)." }, "vdiff_percent_month": { "type": [ "number", "null" ], "format": "float", "description": "Monthly view-count growth as a fraction (YouTube)." }, "youtube_last_updated": { "anyOf": [ { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Date when the YouTube playlist was last observed updated." }, "permalink": { "type": [ "string", "null" ], "description": "SoundCloud playlist permalink slug." }, "artist_permalink": { "type": [ "string", "null" ], "description": "SoundCloud permalink slug of the playlist's artist/owner." }, "soundcloud_artist_name": { "type": [ "string", "null" ], "description": "Display name of the playlist's artist on SoundCloud." }, "monthly_diff": { "description": "Monthly difference for the platform-specific stat (SoundCloud)." }, "monthly_diff_percent": { "description": "Monthly difference percent for the platform-specific stat (SoundCloud)." }, "latest": { "description": "Latest value of the platform-specific stat (SoundCloud likes)." }, "soundcloud_updated": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Date when the SoundCloud playlist was last observed updated." }, "with_storefronts": { "type": "boolean", "description": "Whether storefront-level data (`code2s`) is attached to this entry (iTunes)." }, "code2s": { "type": "array", "items": { "type": "string" }, "description": "List of ISO 3166-1 alpha-2 storefronts where the playlist is available (iTunes)." }, "chart": { "type": "boolean", "description": "Whether the playlist is a platform chart playlist (e.g. Top 50)." }, "radio": { "type": "boolean", "description": "Whether the playlist is an algorithmic radio-style playlist seeded from a track or artist." }, "music_brand_curator": { "type": "boolean", "description": "Whether the curator is a music-industry brand (label or music publication)." }, "non_music_brand_curator": { "type": "boolean", "description": "Whether the curator is a non-music-industry brand (retailer, media outlet, lifestyle)." }, "editorial_brand": { "type": "boolean", "description": "Whether the playlist is an editorial playlist operated by a brand." }, "indie_curator": { "type": "boolean", "description": "Whether the curator is classified as indie (not editorial / brand / major-label)." }, "personality_artist_curator": { "type": "boolean", "description": "Whether the curator is a personality artist (artist with influence beyond their music)." }, "curator_id": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "string" } ], "nullable": true, "description": "Chartmetric curator ID for the playlist owner." }, "chart_ranks": { "type": "array", "items": {}, "description": "Recent chart-rank history of the playlist on the platform (iTunes)." }, "rank": { "type": [ "integer", "null" ], "description": "Playlist's current rank within Amazon's editorial listing." }, "moods": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 0, "description": "Chartmetric mood ID." }, "name": { "type": [ "string", "null" ], "description": "Mood name (e.g. `Chill`, `Energetic`)." } }, "required": [ "id" ] }, "description": "List of moods associated with the playlist." }, "activities": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 0, "description": "Chartmetric mood ID." }, "name": { "type": [ "string", "null" ], "description": "Mood name (e.g. `Chill`, `Energetic`)." } }, "required": [ "id" ] }, "description": "List of activities associated with the playlist." }, "mood_smart_ordered": { "type": [ "array", "null" ], "items": {}, "description": "Moods sorted by relevance via the smart-ordering algorithm." }, "activity_smart_ordered": { "type": [ "array", "null" ], "items": {}, "description": "Activities sorted by relevance via the smart-ordering algorithm." } }, "required": [ "id" ] }, "description": "List of playlists matching the filters and sort." }, "offset": { "type": "integer", "minimum": 0, "description": "Echo of the request `offset` for client-side pagination tracking." }, "total": { "type": "integer", "minimum": 0, "description": "Total number of playlists matching the filters before `limit`/`offset` are applied." } }, "required": [ "obj", "offset", "total" ], "additionalProperties": false }, "examples": { "default": { "value": { "obj": [ { "position": 1, "id": 1645080, "code2": null, "playlist_id": "37i9dQZF1DXcBWIGoYBM5M", "name": "Today's Top Hits", "image_url": "https://i.scdn.co/image/ab67706f00000003a3b1c73cabef96367d1fc553", "personalized": false, "followers": 27093574, "last_updated": "2020-12-21T06:55:23.752Z", "owner_name": "Spotify", "owner_id": 2, "user_id": "spotify", "editorial": true, "fdiff_week": 15895, "fdiff_percent_week": 0.05866704777, "fdiff_month": 56338, "fdiff_percent_month": 0.2079386057, "catalog": "frontline ", "active_ratio": 1, "genre": "pop, top lists" } ], "offset": 0, "total": 1436332 } } } } } } } } }, "/api/playlist/soundcloud/lists": { "get": { "summary": "List Soundcloud Playlists", "tags": [ "Playlist" ], "operationId": "listPlaylistsSoundcloud", "description": "List soundcloud playlists with filters (flags, catalogs, tags, moods, activities, etc.), sorting, and pagination. Response shape varies slightly per platform (e.g. Spotify exposes `followers`/`fdiff_*`, YouTube exposes `views`/`vdiff_*`, SoundCloud exposes `latest`/`monthly_diff`). Reach/follower columns may exceed the 32-bit range.", "parameters": [ { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate. `offset + limit` must be ≤ 10,000 (Elasticsearch window)." }, "required": false, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate. `offset + limit` must be ≤ 10,000 (Elasticsearch window)." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 0, "description": "Maximum number of playlists to return per request. Defaults to 50; max 10000. `offset + limit` must be ≤ 10,000.", "default": 50 }, "required": false, "description": "Maximum number of playlists to return per request. Defaults to 50; max 10000. `offset + limit` must be ≤ 10,000." }, { "name": "sortColumn", "in": "query", "schema": { "type": "string", "enum": [ "active_ratio", "last_updated", "num_track", "latest.likes", "latest.reposts" ], "description": "Column to sort playlists by. Allowed values vary per platform; default also varies per platform.", "default": "latest.likes" }, "required": false, "description": "Column to sort playlists by. Allowed values vary per platform; default also varies per platform." }, { "name": "sortOrderDesc", "in": "query", "schema": { "type": "boolean", "description": "If true, sort `sortColumn` in descending order. Defaults to true.", "default": true }, "required": false, "description": "If true, sort `sortColumn` in descending order. Defaults to true." }, { "name": "indie", "in": "query", "schema": { "type": "boolean", "description": "Filter to only playlists tagged as indie (independently curated)." }, "required": false, "description": "Filter to only playlists tagged as indie (independently curated)." }, { "name": "editorial", "in": "query", "schema": { "type": "boolean", "description": "Filter to only editorial playlists curated by the platform (e.g. Spotify-owned). Defaults to true; pass `false` to include user-curated playlists.", "default": true }, "required": false, "description": "Filter to only editorial playlists curated by the platform (e.g. Spotify-owned). Defaults to true; pass `false` to include user-curated playlists." }, { "name": "topPlaylist", "in": "query", "schema": { "type": "boolean", "description": "Filter to only top playlists (high-reach, frequently-updated playlists curated by Chartmetric editors)." }, "required": false, "description": "Filter to only top playlists (high-reach, frequently-updated playlists curated by Chartmetric editors)." }, { "name": "descriptionSearch", "in": "query", "schema": { "type": "string", "description": "Substring match against the playlist description." }, "required": false, "description": "Substring match against the playlist description." }, { "name": "userListIds[]", "in": "query", "schema": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "uniqueItems": true, "description": "Filter by Chartmetric shortlist (user list) IDs the playlist is included on. Public API exposes this as `shortlistIds`." }, "required": false, "description": "Filter by Chartmetric shortlist (user list) IDs the playlist is included on. Public API exposes this as `shortlistIds`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "array", "items": { "type": "object", "properties": { "position": { "type": "integer", "minimum": 0, "description": "Absolute position of the playlist in the result set after filtering and sorting (1-indexed, accounts for `offset`)." }, "id": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "string" } ], "description": "Chartmetric playlist ID. Numeric for Spotify/iTunes/Deezer; string for Amazon (ASIN) and YouTube (channel/playlist ID)." }, "name": { "type": [ "string", "null" ], "description": "Playlist name." }, "image_url": { "type": [ "string", "null" ], "description": "Cover image URL." }, "description": { "type": [ "string", "null" ], "description": "Playlist description as set by the curator." }, "active_ratio": { "type": [ "number", "null" ], "format": "float", "description": "Ratio (0–1) measuring how actively the playlist is being updated." }, "num_track": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "nullable": true, "description": "Total number of tracks currently on the playlist." }, "last_updated": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Date when Chartmetric last observed an update to the playlist." }, "owner_id": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "nullable": true, "description": "Chartmetric curator (owner) ID for the playlist." }, "owner_name": { "type": [ "string", "null" ], "description": "Display name of the playlist owner." }, "code2": { "type": [ "string", "null" ], "description": "Country code associated with the playlist as ISO 3166-1 alpha-2 (e.g. 'US')." }, "editorial": { "type": "boolean", "description": "Whether the playlist is curated by an official editorial team. Applies mainly to Spotify, Apple Music, and Deezer." }, "genre": { "type": [ "string", "null" ], "description": "Comma-separated list of genres associated with the playlist." }, "followers": { "type": [ "integer", "null" ], "minimum": 0, "description": "Current follower/fan count of the playlist (Spotify followers, Deezer fans). May exceed the 32-bit range." }, "fdiff_week": { "type": [ "integer", "null" ], "description": "Difference in followers/likes vs. one week ago (weekly net growth)." }, "fdiff_percent_week": { "type": [ "number", "null" ], "format": "float", "description": "Weekly follower/like growth as a fraction of the prior value (e.g. `0.05` means +5%)." }, "fdiff_month": { "type": [ "integer", "null" ], "description": "Difference in followers/likes vs. one month ago (monthly net growth)." }, "fdiff_percent_month": { "type": [ "number", "null" ], "format": "float", "description": "Monthly follower/like growth as a fraction of the prior value." }, "playlist_id": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "string" } ], "nullable": true, "description": "Platform-native playlist ID (e.g. Spotify URI suffix)." }, "user_id": { "type": [ "string", "null" ], "description": "Platform-native owner/user ID (e.g. Spotify user ID)." }, "catalog": { "type": [ "string", "null" ], "description": "Catalog classification of the playlist tracks (e.g. `frontline`, `catalogue`, `mixed`)." }, "personalized": { "type": "boolean", "description": "Whether the playlist is personalized (varies per listener, e.g. Discover Weekly)." }, "playlist_updated": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Date when the playlist contents (track list) were last changed." }, "tag_ids": { "type": [ "array", "null" ], "items": { "type": "integer", "minimum": 0 }, "description": "Chartmetric tag/genre IDs associated with the playlist." }, "suspicion_score": { "type": [ "number", "null" ], "format": "float", "description": "Score indicating likelihood of suspicious activity on the playlist (0–100). Higher means more suspicious." }, "submithub_url": { "type": [ "string", "null" ], "description": "SubmitHub submission URL for the playlist's curator, if available." }, "groover_url": { "type": [ "string", "null" ], "description": "Groover submission URL for the playlist's curator, if available." }, "score_100": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric's 0–100 quality score for the playlist." }, "views": { "type": [ "integer", "null" ], "minimum": 0, "description": "Current view count of the playlist (YouTube). May exceed the 32-bit range." }, "vdiff_week": { "type": [ "integer", "null" ], "description": "Difference in views vs. one week ago (YouTube)." }, "vdiff_percent_week": { "type": [ "number", "null" ], "format": "float", "description": "Weekly view-count growth as a fraction (YouTube)." }, "vdiff_month": { "type": [ "integer", "null" ], "description": "Difference in views vs. one month ago (YouTube)." }, "vdiff_percent_month": { "type": [ "number", "null" ], "format": "float", "description": "Monthly view-count growth as a fraction (YouTube)." }, "youtube_last_updated": { "anyOf": [ { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Date when the YouTube playlist was last observed updated." }, "permalink": { "type": [ "string", "null" ], "description": "SoundCloud playlist permalink slug." }, "artist_permalink": { "type": [ "string", "null" ], "description": "SoundCloud permalink slug of the playlist's artist/owner." }, "soundcloud_artist_name": { "type": [ "string", "null" ], "description": "Display name of the playlist's artist on SoundCloud." }, "monthly_diff": { "description": "Monthly difference for the platform-specific stat (SoundCloud)." }, "monthly_diff_percent": { "description": "Monthly difference percent for the platform-specific stat (SoundCloud)." }, "latest": { "description": "Latest value of the platform-specific stat (SoundCloud likes)." }, "soundcloud_updated": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Date when the SoundCloud playlist was last observed updated." }, "with_storefronts": { "type": "boolean", "description": "Whether storefront-level data (`code2s`) is attached to this entry (iTunes)." }, "code2s": { "type": "array", "items": { "type": "string" }, "description": "List of ISO 3166-1 alpha-2 storefronts where the playlist is available (iTunes)." }, "chart": { "type": "boolean", "description": "Whether the playlist is a platform chart playlist (e.g. Top 50)." }, "radio": { "type": "boolean", "description": "Whether the playlist is an algorithmic radio-style playlist seeded from a track or artist." }, "music_brand_curator": { "type": "boolean", "description": "Whether the curator is a music-industry brand (label or music publication)." }, "non_music_brand_curator": { "type": "boolean", "description": "Whether the curator is a non-music-industry brand (retailer, media outlet, lifestyle)." }, "editorial_brand": { "type": "boolean", "description": "Whether the playlist is an editorial playlist operated by a brand." }, "indie_curator": { "type": "boolean", "description": "Whether the curator is classified as indie (not editorial / brand / major-label)." }, "personality_artist_curator": { "type": "boolean", "description": "Whether the curator is a personality artist (artist with influence beyond their music)." }, "curator_id": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "string" } ], "nullable": true, "description": "Chartmetric curator ID for the playlist owner." }, "chart_ranks": { "type": "array", "items": {}, "description": "Recent chart-rank history of the playlist on the platform (iTunes)." }, "rank": { "type": [ "integer", "null" ], "description": "Playlist's current rank within Amazon's editorial listing." }, "moods": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 0, "description": "Chartmetric mood ID." }, "name": { "type": [ "string", "null" ], "description": "Mood name (e.g. `Chill`, `Energetic`)." } }, "required": [ "id" ] }, "description": "List of moods associated with the playlist." }, "activities": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 0, "description": "Chartmetric mood ID." }, "name": { "type": [ "string", "null" ], "description": "Mood name (e.g. `Chill`, `Energetic`)." } }, "required": [ "id" ] }, "description": "List of activities associated with the playlist." }, "mood_smart_ordered": { "type": [ "array", "null" ], "items": {}, "description": "Moods sorted by relevance via the smart-ordering algorithm." }, "activity_smart_ordered": { "type": [ "array", "null" ], "items": {}, "description": "Activities sorted by relevance via the smart-ordering algorithm." } }, "required": [ "id" ] }, "description": "List of playlists matching the filters and sort." }, "offset": { "type": "integer", "minimum": 0, "description": "Echo of the request `offset` for client-side pagination tracking." }, "total": { "type": "integer", "minimum": 0, "description": "Total number of playlists matching the filters before `limit`/`offset` are applied." } }, "required": [ "obj", "offset", "total" ], "additionalProperties": false }, "examples": { "default": { "value": { "obj": [ { "position": 1, "id": 1645080, "code2": null, "playlist_id": "37i9dQZF1DXcBWIGoYBM5M", "name": "Today's Top Hits", "image_url": "https://i.scdn.co/image/ab67706f00000003a3b1c73cabef96367d1fc553", "personalized": false, "followers": 27093574, "last_updated": "2020-12-21T06:55:23.752Z", "owner_name": "Spotify", "owner_id": 2, "user_id": "spotify", "editorial": true, "fdiff_week": 15895, "fdiff_percent_week": 0.05866704777, "fdiff_month": 56338, "fdiff_percent_month": 0.2079386057, "catalog": "frontline ", "active_ratio": 1, "genre": "pop, top lists" } ], "offset": 0, "total": 1436332 } } } } } } } } }, "/api/playlist/{platform}/{id}": { "get": { "summary": "Get Playlist Metadata", "tags": [ "Playlist" ], "operationId": "getPlaylistById", "description": "Fetch metadata for a Chartmetric playlist on a streaming platform. Response shape varies slightly per platform; follower counts may exceed the 32-bit range.", "parameters": [ { "name": "id", "in": "path", "schema": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 2147483647, "x-required": true }, { "x-required": true } ], "description": "Chartmetric playlist ID. Numeric for `spotify`, `itunes`/`applemusic`, and `deezer`; string (e.g. ASIN, channel ID) for `amazon`, `youtube`, and `soundcloud`." }, "required": true, "description": "Chartmetric playlist ID. Numeric for `spotify`, `itunes`/`applemusic`, and `deezer`; string (e.g. ASIN, channel ID) for `amazon`, `youtube`, and `soundcloud`.", "examples": { "default": { "value": 1 } } }, { "name": "platform", "in": "path", "schema": { "type": "string", "enum": [ "cm", "spotify", "itunes", "applemusic", "deezer", "shazam", "beatport", "amazon", "youtube", "tunefind", "soundcloud" ], "description": "Streaming platform. One of `spotify`, `applemusic` (aliased to `itunes`), `itunes`, `deezer`, `amazon`, `youtube`, `soundcloud`." }, "required": true, "description": "Streaming platform. One of `spotify`, `applemusic` (aliased to `itunes`), `itunes`, `deezer`, `amazon`, `youtube`, `soundcloud`.", "examples": { "default": { "value": "cm" } } }, { "name": "storefront", "in": "query", "schema": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB')." }, "required": false, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB')." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric playlist ID." }, "name": { "type": [ "string", "null" ], "description": "Playlist name." }, "playlist_id": { "type": [ "string", "null" ], "description": "Platform-native playlist ID (e.g. Spotify URI suffix)." }, "description": { "type": [ "string", "null" ], "description": "Playlist description as set by the curator." }, "image_url": { "type": [ "string", "null" ], "description": "Cover image URL." }, "sys_last_updated": { "anyOf": [ { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Date when Chartmetric last refreshed playlist data." }, "last_updated": { "anyOf": [ { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Date when the playlist was last observed updated on the platform." }, "personalized": { "type": "boolean", "description": "Whether the playlist is personalized (varies per listener)." }, "code2": { "type": [ "string", "null" ], "description": "Country code associated with the playlist as ISO 3166-1 alpha-2 (e.g. 'US')." }, "owner_name": { "type": [ "string", "null" ], "description": "Display name of the playlist owner." }, "owner_id": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "nullable": true, "description": "Chartmetric curator (owner) ID for the playlist." }, "user_id": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "nullable": true, "description": "Platform-native owner/user ID (e.g. Spotify user ID)." }, "editorial": { "type": "boolean", "description": "Whether the playlist is curated by an official editorial team. Applies mainly to Spotify, Apple Music, and Deezer." }, "tags": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 0, "description": "Chartmetric tag/genre ID." }, "name": { "type": "string", "description": "Tag/genre name." }, "source": { "type": [ "string", "null" ], "description": "Source of the tag (e.g. `spotify`)." }, "type": { "type": [ "string", "null" ], "description": "Tag type (e.g. `genre`, `mood`)." }, "url": { "type": [ "string", "null" ], "description": "Optional URL associated with the tag." }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the tag association was first observed." }, "modified_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the tag association was last updated." } }, "required": [ "id", "name" ] }, "description": "List of tags/genres on the playlist." }, "followers": { "type": [ "integer", "null" ], "minimum": 0, "description": "Current follower/fan count of the playlist. May exceed the 32-bit range on Spotify/Deezer." }, "likes": { "type": [ "integer", "null" ], "minimum": 0, "description": "Current like count of the playlist (SoundCloud)." }, "num_track": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "nullable": true, "description": "Total number of tracks currently on the playlist." }, "fdiff_week": { "type": [ "integer", "null" ], "description": "Difference in followers/likes vs. one week ago (weekly net growth)." }, "fdiff_month": { "type": [ "integer", "null" ], "description": "Difference in followers/likes vs. one month ago (monthly net growth)." }, "catalog": { "type": [ "string", "null" ], "description": "Catalog classification of the playlist tracks (e.g. `frontline`, `catalogue`, `mixed`)." }, "active_ratio": { "type": [ "number", "null" ], "format": "float", "description": "Ratio (0–1) measuring how actively the playlist is being updated." }, "new_sp_id": { "type": [ "string", "null" ], "description": "New Spotify playlist ID if the playlist has been transferred to a new owner." }, "moods": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 0, "description": "Chartmetric mood ID." }, "name": { "type": [ "string", "null" ], "description": "Mood name (e.g. `Chill`, `Energetic`)." } }, "required": [ "id" ] }, "description": "List of moods associated with the playlist." }, "activities": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 0, "description": "Chartmetric mood ID." }, "name": { "type": [ "string", "null" ], "description": "Mood name (e.g. `Chill`, `Energetic`)." } }, "required": [ "id" ] }, "description": "List of activities associated with the playlist." }, "genres": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 0, "description": "Chartmetric genre ID." }, "name": { "type": [ "string", "null" ], "description": "Genre name." } }, "required": [ "id" ] }, "description": "List of genres associated with the playlist." } }, "required": [ "id" ] } }, "additionalProperties": false }, "examples": { "default": { "value": { "obj": { "id": 179228, "name": "Disney Hits", "playlist_id": "5NtjgKz4doejP5HJtKXFcS", "description": "Your favorite Disney songs including Disney and Pixar’s Soul soundtrack.", "image_url": "https://i.scdn.co/image/ab67706c0000bebb5eb3284524c46bb313c1901f", "sys_last_updated": "2020-12-20T02:54:08.370Z", "last_updated": "2020-12-19T03:57:31.173Z", "personalized": false, "code2": null, "owner_name": "Walt Disney Records", "owner_id": 40857, "user_id": "128899670", "editorial": false, "tags": [ { "id": 12463, "name": "hollywood" }, { "id": 25588, "name": "movie tunes" }, { "id": 408416, "name": "pop" } ], "followers": 11334, "num_track": "88", "fdiff_week": 68, "fdiff_month": 425, "catalog": "catalogue ", "active_ratio": 0.034091 } } } } } } } } } }, "/api/playlist/{platform}/{id}/stats": { "get": { "summary": "Get Playlist Stats Over Time", "tags": [ "Playlist" ], "operationId": "getPlaylistStats", "description": "Time series of playlist audience stats (Spotify followers / Deezer fans / YouTube views / SoundCloud likes) over a date range.", "parameters": [ { "name": "id", "in": "path", "schema": { "anyOf": [ { "type": "string" }, { "type": "integer" } ], "description": "Chartmetric playlist ID (not the platform-native ID). Numeric for `spotify`/`deezer`/`soundcloud`; string for `youtube`." }, "required": true, "description": "Chartmetric playlist ID (not the platform-native ID). Numeric for `spotify`/`deezer`/`soundcloud`; string for `youtube`.", "examples": { "default": { "value": "2762" } } }, { "name": "platform", "in": "path", "schema": { "type": "string", "enum": [ "spotify", "deezer", "youtube", "soundcloud" ], "description": "Streaming platform. One of `spotify`, `deezer`, `youtube`, `soundcloud`. Stat type varies by platform: Spotify followers, Deezer fans, YouTube views, SoundCloud likes." }, "required": true, "description": "Streaming platform. One of `spotify`, `deezer`, `youtube`, `soundcloud`. Stat type varies by platform: Spotify followers, Deezer fans, YouTube views, SoundCloud likes.", "examples": { "default": { "value": "spotify" } } }, { "name": "since", "in": "query", "schema": { "type": "string", "format": "date", "description": "Inclusive start of the date range in `YYYY-MM-DD` format. Defaults to 180 days before today.", "default": "2026-05-09" }, "required": false, "description": "Inclusive start of the date range in `YYYY-MM-DD` format. Defaults to 180 days before today." }, { "name": "until", "in": "query", "schema": { "type": "string", "format": "date", "description": "Inclusive end of the date range in `YYYY-MM-DD` format. Defaults to today.", "default": "2026-11-05" }, "required": false, "description": "Inclusive end of the date range in `YYYY-MM-DD` format. Defaults to today." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Internal stat row ID. `null` for a day only an on-demand refresh has written so far." }, "value": { "type": "integer", "minimum": 0, "description": "Stat value at this timestamp. Meaning varies by platform: Spotify followers, Deezer fans, YouTube views, SoundCloud likes." }, "timestp": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "description": "Timestamp of the data point." }, "daily_diff": { "type": [ "integer", "null" ], "description": "Day-over-day change in `value`." }, "weekly_diff": { "type": [ "integer", "null" ], "description": "Week-over-week change in `value`." }, "weekly_diff_percent": { "type": [ "number", "null" ], "format": "float", "description": "Week-over-week change as a fraction of the prior value." }, "monthly_diff": { "type": [ "integer", "null" ], "description": "Month-over-month change in `value`." }, "monthly_diff_percent": { "type": [ "number", "null" ], "format": "float", "description": "Month-over-month change as a fraction of the prior value." }, "interpolated": { "type": "boolean", "description": "Whether `value` was interpolated to fill a gap in source data." }, "extrapolated": { "type": "boolean", "description": "Whether `value` was extrapolated past the latest source data point." }, "flags": { "type": "boolean", "description": "Whether the stat row is flagged for review." } }, "required": [ "value", "timestp" ] } } }, "required": [ "obj" ], "additionalProperties": false }, "examples": { "default": { "value": { "obj": [ { "id": 93878425, "value": 6527755, "timestp": "Thu Oct 10 2019", "daily_diff": 0, "interpolated": false } ] } } } } } } } } }, "/api/playlist/{platform}/{id}/snapshot": { "get": { "summary": "Get Playlist Snapshot on a Date", "tags": [ "Playlist" ], "operationId": "getPlaylistSnapshot", "description": "Returns the tracks that were on the playlist on the given `date`, each enriched with basic track info (name, ISRC, artists, album metadata).", "parameters": [ { "name": "id", "in": "path", "schema": { "description": "Chartmetric playlist ID. Numeric for `spotify`, `itunes`/`applemusic`, `deezer`; string for `amazon` (e.g. ASIN), `youtube`, and `soundcloud`." }, "required": true, "description": "Chartmetric playlist ID. Numeric for `spotify`, `itunes`/`applemusic`, `deezer`; string for `amazon` (e.g. ASIN), `youtube`, and `soundcloud`.", "examples": { "default": { "value": "2762" } } }, { "name": "platform", "in": "path", "schema": { "type": "string", "enum": [ "cm", "spotify", "itunes", "applemusic", "deezer", "shazam", "beatport", "amazon", "youtube", "tunefind", "soundcloud" ], "description": "Streaming platform. One of `spotify`, `applemusic` (aliased to `itunes`), `deezer`, `amazon`, `youtube`, `soundcloud`." }, "required": true, "description": "Streaming platform. One of `spotify`, `applemusic` (aliased to `itunes`), `deezer`, `amazon`, `youtube`, `soundcloud`.", "examples": { "default": { "value": "cm" } } }, { "name": "storefront", "in": "query", "schema": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB')." }, "required": false, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB')." }, { "name": "date", "in": "query", "schema": { "type": "string", "format": "date-time", "description": "Snapshot date. Returns the tracks that were on the playlist on this date (`YYYY-MM-DD`)." }, "required": true, "description": "Snapshot date. Returns the tracks that were on the playlist on this date (`YYYY-MM-DD`).", "examples": { "default": { "value": "2024-01-01" } } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "array", "items": { "type": "object", "properties": { "track_id": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Internal track-row ID." }, "id": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Internal track-row ID." }, "added_at": { "anyOf": [ { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Date when the track was added to the playlist." }, "removed_at": { "anyOf": [ { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Date when the track was detected as no longer being on the playlist; null if still present." }, "position": { "type": [ "integer", "null" ], "description": "Track's position in the playlist (1-indexed)." }, "name": { "type": [ "string", "null" ], "description": "Track name." }, "isrc": { "type": [ "string", "null" ], "description": "International Standard Recording Code (ISRC) of the track." }, "spotify_track_id": { "type": [ "string", "null" ], "description": "Spotify track ID." }, "spotify_album_id": { "type": [ "string", "null" ], "description": "Spotify album ID for the album containing the track." }, "image_url": { "type": [ "string", "null" ], "description": "Album cover image URL." }, "spotify_popularity": { "type": [ "integer", "null" ], "description": "Spotify's 0–100 popularity score for the track." }, "cm_track": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric track ID." }, "spotify_artist_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Artist display names as they appear on Spotify." }, "track_genre": { "type": [ "string", "null" ], "description": "Comma-separated list of genres associated with the track." }, "cm_artist": { "type": [ "array", "null" ], "items": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "description": "Chartmetric artist IDs for the credited artists." }, "artist_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Artist display names from Chartmetric." }, "code2s": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Country codes (ISO 3166-1 alpha-2) of the credited artists' origins." }, "artist_images": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Profile image URLs for the credited artists." }, "artist_covers": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Cover image URLs for the credited artists." }, "spotify_artist_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Spotify artist IDs for the credited artists." }, "spotify_track_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "All Spotify track IDs that map to this Chartmetric track (covers re-releases)." }, "spotify_album_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "All Spotify album IDs that contain this track." }, "spotify_duration_ms": { "type": [ "integer", "null" ], "description": "Track duration in milliseconds (Spotify)." }, "album_ids": { "type": [ "array", "null" ], "items": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "description": "Chartmetric album IDs for the albums containing this track." }, "album_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Album titles." }, "album_upc": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Universal Product Codes (UPC) for the albums." }, "album_label": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Record labels that released the albums." }, "release_dates": { "type": [ "array", "null" ], "items": { "anyOf": [ { "type": "string", "format": "date-time" } ], "nullable": true }, "description": "Album release dates." }, "preview_url": { "type": [ "string", "null" ], "description": "Spotify 30-second preview URL for the track, if available." }, "storefront": { "type": [ "string", "null" ], "description": "Storefront the snapshot was taken from (e.g. 'us' for Apple Music)." } } } } }, "required": [ "obj" ], "additionalProperties": false }, "examples": { "default": { "value": { "obj": [ { "track_id": 16979872, "id": 16979872, "added_at": "2020-01-22T00:00:00.000Z", "removed_at": null, "position": 1, "name": "Into the Unknown", "isrc": "USWD11994667", "spotify_track_id": "3Z0oQ8r78OUaHvGPiDBR3W", "spotify_album_id": "4M07HWIlZr7zoXoxDHR5mz", "image_url": "https://i.scdn.co/image/43c6b410f1bc66fac51d61f36e3149b29b3f25f1", "spotify_popularity": 79, "cm_track": 27031598, "spotify_artist_names": [ "Idina Menzel", "AURORA" ], "track_genre": "broadway,hollywood,movie tunes,show tunes,norwegian pop,pop", "cm_artist": [ 1805, 5172 ], "artist_names": [ "Idina Menzel", "AURORA" ], "code2s": [ "US", "NO" ], "artist_images": [ "https://i.scdn.co/image/e303c5a39e4da4f7c40f1b6ccc1209795c9199d0", "https://i.scdn.co/image/a3ade0a92bb3c99514fb8d017024a7d9df1572b1" ], "artist_covers": [ null, null ], "spotify_artist_ids": [ "73Np75Wv2tju61Eo9Zw4IR", "1WgXqy2Dd70QQOU7Ay074N" ], "spotify_track_ids": [ "3Z0oQ8r78OUaHvGPiDBR3W" ], "spotify_album_ids": [ "4M07HWIlZr7zoXoxDHR5mz" ], "spotify_duration_ms": 194848, "album_ids": [ 5357061 ], "album_names": [ "Frozen 2 (Original Motion Picture Soundtrack/Deluxe Edition)" ], "album_upc": [ "050087433390" ], "album_label": [ "Walt Disney Records" ], "release_dates": [ "2019-11-15T00:00:00.000Z" ] } ] } } } } } } } } }, "/api/playlist/{platform}/{id}/similarplaylists": { "get": { "summary": "Get Similar Playlists", "tags": [ "Playlist" ], "operationId": "listPlaylistSimilarPlaylists", "description": "Return playlists similar to the target playlist on the given platform (Spotify or SoundCloud), with overlap flags for shared moods/genres.", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer", "description": "Chartmetric playlist ID." }, "required": true, "description": "Chartmetric playlist ID.", "examples": { "default": { "value": 1 } } }, { "name": "platform", "in": "path", "schema": { "type": "string", "enum": [ "spotify", "soundcloud" ], "description": "Streaming platform. One of `spotify` or `soundcloud`." }, "required": true, "description": "Streaming platform. One of `spotify` or `soundcloud`.", "examples": { "default": { "value": "spotify" } } }, { "name": "indie", "in": "query", "schema": { "type": "boolean", "description": "If true, return only indie-curated similar playlists. Defaults to false.", "default": false }, "required": false, "description": "If true, return only indie-curated similar playlists. Defaults to false." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum number of items to return per request.", "default": 10 }, "required": false, "description": "Maximum number of items to return per request." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, "required": false, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "array", "items": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "description": "Chartmetric playlist ID of the similar playlist." }, "playlist_id": { "type": [ "string", "null" ], "description": "Platform-native playlist ID (e.g. Spotify URI suffix)." }, "name": { "type": [ "string", "null" ], "description": "Playlist name." }, "image_url": { "type": [ "string", "null" ], "description": "Cover image URL." }, "followers": { "type": [ "integer", "null" ], "minimum": 0, "description": "Current follower count of the similar playlist (Spotify)." }, "likes": { "type": [ "integer", "null" ], "minimum": 0, "description": "Current like count of the similar playlist (SoundCloud)." }, "genre": { "type": [ "string", "null" ], "description": "Comma-separated list of genres associated with the playlist." }, "permalink": { "type": [ "string", "null" ], "description": "SoundCloud playlist permalink slug." }, "owner_name": { "type": [ "string", "null" ], "description": "Display name of the playlist owner." }, "owner_permalink": { "type": [ "string", "null" ], "description": "SoundCloud permalink slug of the playlist owner." }, "user_id": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "nullable": true, "description": "Platform-native owner/user ID." }, "owner_id": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "nullable": true, "description": "Chartmetric curator (owner) ID for the playlist." }, "tags": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 0, "description": "Chartmetric tag/genre ID." }, "name": { "type": "string", "description": "Tag/genre name." }, "source": { "type": [ "string", "null" ], "description": "Source of the tag (e.g. `spotify`)." }, "type": { "type": [ "string", "null" ], "description": "Tag type (e.g. `genre`, `mood`)." }, "url": { "type": [ "string", "null" ], "description": "Optional URL associated with the tag." }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the tag association was first observed." }, "modified_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the tag association was last updated." } }, "required": [ "id", "name" ] }, "description": "List of tags/genres on the similar playlist." }, "genres": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 0, "description": "Chartmetric genre ID." }, "name": { "type": [ "string", "null" ], "description": "Genre name." }, "isOverlappingGenre": { "type": "boolean", "description": "Whether this genre is shared with the target playlist." } }, "required": [ "id" ] }, "description": "List of genres on the similar playlist with overlap flags." }, "moods": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 0, "description": "Chartmetric mood ID." }, "name": { "type": [ "string", "null" ], "description": "Mood name (e.g. `Chill`, `Energetic`)." }, "isOverlappingMood": { "type": "boolean", "description": "Whether this mood is shared with the target playlist." } }, "required": [ "id" ] }, "description": "List of moods on the similar playlist with overlap flags." }, "isOverlappingGenre": { "type": "boolean", "description": "Whether the playlist shares at least one genre with the target." } }, "required": [ "id" ] } } }, "required": [ "obj" ], "additionalProperties": false }, "examples": { "default": { "value": { "obj": [ { "id": 1816590, "playlist_id": "37i9dQZF1DX8C9xQcOrE6T", "name": "Disney Hits", "image_url": "https://i.scdn.co/image/ab67706f000000034fb035ee54262509612d6900", "followers": 3525555, "owner_name": "Spotify", "user_id": "spotify", "owner_id": 2, "tags": [ { "id": 12463, "name": "hollywood", "source": "spotify", "type": "genre", "url": null, "created_at": null, "modified_at": null } ] } ] } } } } } } } } }, "/api/playlist/{platform}/{id}/{span}/tracks": { "get": { "summary": "List Playlist Tracks (Current or Past)", "tags": [ "Playlist" ], "operationId": "listPlaylistTracks", "description": "List tracks currently on or previously on a playlist, optionally enriched with artist/album/audio-feature details. Use `span=current` for active tracks, `span=past` for historical removals.", "parameters": [ { "name": "id", "in": "path", "schema": { "anyOf": [ { "type": "string" }, { "type": "integer" } ], "description": "Chartmetric playlist ID. Numeric for `spotify`/`itunes`/`deezer`/`soundcloud`; string for `amazon`/`youtube`." }, "required": true, "description": "Chartmetric playlist ID. Numeric for `spotify`/`itunes`/`deezer`/`soundcloud`; string for `amazon`/`youtube`.", "examples": { "default": { "value": "2762" } } }, { "name": "platform", "in": "path", "schema": { "type": "string", "enum": [ "cm", "spotify", "itunes", "applemusic", "deezer", "shazam", "beatport", "amazon", "youtube", "tunefind", "soundcloud" ], "description": "Streaming platform. One of `spotify`, `itunes`, `deezer`, `amazon`, `youtube`, `soundcloud`." }, "required": true, "description": "Streaming platform. One of `spotify`, `itunes`, `deezer`, `amazon`, `youtube`, `soundcloud`.", "examples": { "default": { "value": "cm" } } }, { "name": "span", "in": "path", "schema": { "type": "string", "enum": [ "current", "past" ], "description": "Time span. `current` returns tracks currently on the playlist; `past` returns tracks that were on the playlist but have since been removed." }, "required": true, "description": "Time span. `current` returns tracks currently on the playlist; `past` returns tracks that were on the playlist but have since been removed.", "examples": { "default": { "value": "current" } } }, { "name": "withDetails", "in": "query", "schema": { "type": "boolean", "description": "If true, hydrate each track with artist, album, and audio-feature details. Defaults to true.", "default": true }, "required": false, "description": "If true, hydrate each track with artist, album, and audio-feature details. Defaults to true." }, { "name": "since", "in": "query", "schema": { "type": "string", "format": "date", "description": "Only return tracks with `removed_at` after this date in `YYYY-MM-DD` format. Applies only to `span=past`." }, "required": false, "description": "Only return tracks with `removed_at` after this date in `YYYY-MM-DD` format. Applies only to `span=past`." }, { "name": "until", "in": "query", "schema": { "type": "string", "format": "date", "description": "Only return tracks with `added_at` before this date in `YYYY-MM-DD` format. Applies only to `span=past`." }, "required": false, "description": "Only return tracks with `added_at` before this date in `YYYY-MM-DD` format. Applies only to `span=past`." }, { "name": "storefront", "in": "query", "schema": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB')." }, "required": false, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB')." }, { "name": "version_only[]", "in": "query", "schema": { "type": "array", "items": { "type": "string", "enum": [ "original", "re_release", "edit", "remix", "acoustic", "alt_ver", "physical_ver", "cover", "live", "feat_or_collab", "dub", "remaster", "bonus", "arrangement", "commentary", "lofi", "component", "karaoke", "compilation_rerelease", "explicit", "clean", "other" ] }, "description": "Filter to tracks where ONLY the specified version cluster types are true and all others are false. Cannot be combined with `version_and`, `version_or`, or `version_not`." }, "required": false, "description": "Filter to tracks where ONLY the specified version cluster types are true and all others are false. Cannot be combined with `version_and`, `version_or`, or `version_not`." }, { "name": "version_and[]", "in": "query", "schema": { "type": "array", "items": { "type": "string", "enum": [ "original", "re_release", "edit", "remix", "acoustic", "alt_ver", "physical_ver", "cover", "live", "feat_or_collab", "dub", "remaster", "bonus", "arrangement", "commentary", "lofi", "component", "karaoke", "compilation_rerelease", "explicit", "clean", "other" ] }, "description": "Filter to tracks that contain ALL of the specified version cluster types. Cannot be combined with `version_or`." }, "required": false, "description": "Filter to tracks that contain ALL of the specified version cluster types. Cannot be combined with `version_or`." }, { "name": "version_or[]", "in": "query", "schema": { "type": "array", "items": { "type": "string", "enum": [ "original", "re_release", "edit", "remix", "acoustic", "alt_ver", "physical_ver", "cover", "live", "feat_or_collab", "dub", "remaster", "bonus", "arrangement", "commentary", "lofi", "component", "karaoke", "compilation_rerelease", "explicit", "clean", "other" ] }, "description": "Filter to tracks that contain AT LEAST ONE of the specified version cluster types. Cannot be combined with `version_and`." }, "required": false, "description": "Filter to tracks that contain AT LEAST ONE of the specified version cluster types. Cannot be combined with `version_and`." }, { "name": "version_not[]", "in": "query", "schema": { "type": "array", "items": { "type": "string", "enum": [ "original", "re_release", "edit", "remix", "acoustic", "alt_ver", "physical_ver", "cover", "live", "feat_or_collab", "dub", "remaster", "bonus", "arrangement", "commentary", "lofi", "component", "karaoke", "compilation_rerelease", "explicit", "clean", "other" ] }, "description": "Filter to tracks that contain NONE of the specified version cluster types." }, "required": false, "description": "Filter to tracks that contain NONE of the specified version cluster types." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "description": "Maximum number of items to return per request.", "default": 100 }, "required": false, "description": "Maximum number of items to return per request." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, "required": false, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "array", "items": { "type": "object", "properties": { "cm_track_id": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric track ID." }, "track_id": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Internal track-row ID." }, "isrc": { "type": [ "string", "null" ], "description": "International Standard Recording Code (ISRC) of the track." }, "added_at": { "anyOf": [ { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Date when the track was added to the playlist." }, "removed_at": { "anyOf": [ { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Date when the track was detected as no longer being on the playlist; null when `span=current`." }, "position": { "type": [ "integer", "null" ], "description": "Track's position in the playlist (1-indexed)." }, "period": { "type": [ "integer", "null" ], "description": "Number of days the track has been on the playlist." }, "track_name": { "type": [ "string", "null" ], "description": "Track name." }, "name": { "type": [ "string", "null" ], "description": "Track name. Same value as `track_name`." }, "totaltracks": { "type": [ "integer", "null" ], "description": "Total number of tracks currently on the playlist." }, "cluster_types": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Track version cluster types (e.g. 'remix', 'live', 'acoustic')." }, "id": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Internal track-row ID." }, "spotify_album_id": { "type": [ "string", "null" ], "description": "Spotify album ID for the album containing the track." }, "image_url": { "type": [ "string", "null" ], "description": "Album cover image URL." }, "spotify_popularity": { "type": [ "integer", "null" ], "description": "Spotify's 0–100 popularity score for the track." }, "cm_track": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric track ID." }, "spotify_artist_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Artist display names as they appear on Spotify." }, "track_genre": { "type": [ "string", "null" ], "description": "Comma-separated list of genres associated with the track." }, "cm_artist": { "type": [ "array", "null" ], "items": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "description": "Chartmetric artist IDs for the credited artists." }, "artist_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Artist display names from Chartmetric." }, "code2s": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Country codes (ISO 3166-1 alpha-2) of the credited artists' origins." }, "artist_images": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Profile image URLs for the credited artists." }, "artist_covers": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Cover image URLs for the credited artists." }, "spotify_artist_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Spotify artist IDs for the credited artists." }, "spotify_track_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "All Spotify track IDs that map to this Chartmetric track." }, "spotify_album_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "All Spotify album IDs that contain this track." }, "spotify_duration_ms": { "type": [ "integer", "null" ], "description": "Track duration in milliseconds (Spotify)." }, "album_ids": { "type": [ "array", "null" ], "items": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "description": "Chartmetric album IDs for the albums containing this track." }, "album_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Album titles." }, "album_upc": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Universal Product Codes (UPC) for the albums." }, "album_label": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Record labels that released the albums." }, "release_dates": { "type": [ "array", "null" ], "items": { "anyOf": [ { "type": "string", "format": "date-time" } ], "nullable": true }, "description": "Album release dates." }, "audio_features": { "type": [ "object", "null" ], "properties": { "key": { "type": [ "integer", "null" ], "description": "Musical key (0–11; 0 = C, 1 = C♯/D♭, ...). Spotify audio feature." }, "mode": { "type": [ "integer", "null" ], "description": "Modality of the track: 1 = major, 0 = minor. Spotify audio feature." }, "danceability": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "How suitable the track is for dancing (0–1). Spotify audio feature." }, "valence": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Musical positiveness (0–1; higher means happier/cheerful). Spotify audio feature." }, "energy": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Perceptual measure of intensity and activity (0–1). Spotify audio feature." }, "speechiness": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Presence of spoken words (0–1; values >0.66 are likely spoken-word). Spotify audio feature." }, "acousticness": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Confidence that the track is acoustic (0–1). Spotify audio feature." }, "instrumentalness": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Confidence that the track has no vocals (0–1). Spotify audio feature." }, "liveness": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Probability that the track was performed live (0–1). Spotify audio feature." }, "tempo": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Estimated tempo in BPM. Spotify audio feature." }, "loudness": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Overall loudness in dB (typically -60 to 0). Spotify audio feature." } }, "description": "Spotify audio features for the track. Present only when `withDetails=true`." }, "position_stats": { "type": [ "array", "null" ], "items": {}, "description": "Position-history aggregates for the track within the playlist (peak, time at peak, etc.)." }, "preview_url": { "type": [ "string", "null" ], "description": "Spotify 30-second preview URL for the track, if available." }, "storefront": { "type": [ "string", "null" ], "description": "Storefront the track was observed on (e.g. 'us' for Apple Music)." } } } } }, "required": [ "obj" ], "additionalProperties": false }, "examples": { "default": { "value": { "obj": [ { "track_id": 16979872, "isrc": "USWD11994667", "added_at": "2020-01-22T00:00:00.000Z", "position": 1, "period": 334, "id": 16979872, "name": "Into the Unknown", "spotify_album_id": "4M07HWIlZr7zoXoxDHR5mz", "image_url": "https://i.scdn.co/image/43c6b410f1bc66fac51d61f36e3149b29b3f25f1", "spotify_popularity": 79, "cm_track": 27031598, "spotify_artist_names": [ "Idina Menzel", "AURORA" ], "track_genre": "broadway,hollywood,movie tunes,show tunes,norwegian pop,pop", "cm_artist": [ 1805, 5172 ], "artist_names": [ "Idina Menzel", "AURORA" ], "code2s": [ "US", "NO" ], "artist_images": [ "https://i.scdn.co/image/e303c5a39e4da4f7c40f1b6ccc1209795c9199d0", "https://i.scdn.co/image/a3ade0a92bb3c99514fb8d017024a7d9df1572b1" ], "artist_covers": [ null, null ], "spotify_artist_ids": [ "73Np75Wv2tju61Eo9Zw4IR", "1WgXqy2Dd70QQOU7Ay074N" ], "spotify_track_ids": [ "3Z0oQ8r78OUaHvGPiDBR3W" ], "spotify_album_ids": [ "4M07HWIlZr7zoXoxDHR5mz" ], "spotify_duration_ms": 194848, "album_ids": [ 5357061 ], "album_names": [ "Frozen 2 (Original Motion Picture Soundtrack/Deluxe Edition)" ], "album_upc": [ "050087433390" ], "album_label": [ "Walt Disney Records" ], "release_dates": [ "2019-11-15T00:00:00.000Z" ], "audio_features": { "key": 10, "mode": 0, "danceability": "0.323", "energy": "0.405", "speechiness": "0.0413", "acousticness": "0.849", "instrumentalness": "0.000544", "liveness": "0.138", "valence": "0.274", "tempo": "145.104", "loudness": "-8.533" }, "position_stats": [] } ] } } } } } } } } }, "/api/playlist/{platform}/{id}/tracks/{trackId}": { "get": { "summary": "Get a Track's Placement History on a Playlist", "tags": [ "Playlist" ], "operationId": "getTrackPlaylistPlacementHistory", "description": "Direct lookup of a single track on a single playlist, without paging the playlist track lists. Answers in one call whether the track is currently on the playlist (`span: current`), was on it and has been removed (`span: past`, with `removed_at` set), or has never been on it (`found: false`). Top-level fields describe the latest placement; `stints` carries the full placement history — every add→remove cycle. Only `spotify` is currently supported.", "parameters": [ { "name": "id", "in": "path", "schema": { "anyOf": [ { "type": "string" }, { "type": "integer" } ], "description": "Chartmetric playlist ID (not the platform-native ID)." }, "required": true, "description": "Chartmetric playlist ID (not the platform-native ID).", "examples": { "default": { "value": "2762" } } }, { "name": "platform", "in": "path", "schema": { "type": "string", "enum": [ "spotify" ], "description": "Streaming platform. Only `spotify` currently supports direct track lookup." }, "required": true, "description": "Streaming platform. Only `spotify` currently supports direct track lookup.", "examples": { "default": { "value": "spotify" } } }, { "name": "trackId", "in": "path", "schema": { "type": "integer", "description": "Chartmetric track ID to look up on the playlist." }, "required": true, "description": "Chartmetric track ID to look up on the playlist.", "examples": { "default": { "value": 1 } } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "object", "properties": { "found": { "type": "boolean", "description": "Whether the track is on the playlist now or was in the past." }, "span": { "type": [ "string", "null" ], "enum": [ "", "current", "past" ], "description": "`current` when the track is on the playlist now; `past` when it has been removed; `null` when it was never on the playlist." }, "position": { "type": [ "integer", "null" ], "description": "Playlist position of the track (1-based); the latest known position for `span: past`. `null` when not found." }, "peak_position": { "type": [ "integer", "null" ], "description": "Best (lowest-numbered, 1-based) position the track has reached on this playlist across all stints, from daily position samples. `null` when not found or when no samples exist." }, "added_at": { "type": [ "string", "null" ], "description": "Date the track was added to the playlist, `YYYY-MM-DD`. `null` when not found." }, "removed_at": { "type": [ "string", "null" ], "description": "Date the track was removed from the playlist, `YYYY-MM-DD`. `null` while the track is still on the playlist or was never on it." }, "followers": { "type": [ "integer", "null" ], "description": "Follower count of the playlist (latest crawled value). `null` when not found." }, "playlist_type": { "type": [ "object", "null" ], "properties": { "editorial": { "type": "boolean" }, "personalized": { "type": "boolean" }, "fullyPersonalized": { "type": "boolean" }, "chart": { "type": "boolean" }, "thisIs": { "type": "boolean" }, "newMusicFriday": { "type": "boolean" }, "radio": { "type": "boolean" }, "brand": { "type": "boolean" }, "majorCurator": { "type": "boolean" }, "popularIndie": { "type": "boolean" }, "indie": { "type": "boolean" }, "audiobook": { "type": "boolean" } }, "additionalProperties": false, "description": "Curator-type classification of the playlist. Keys match the filter flags accepted by the playlist list endpoints (e.g. `editorial`, `majorCurator`, `newMusicFriday`). `null` when not found." }, "stints": { "type": "array", "items": { "type": "object", "properties": { "added_at": { "type": "string", "description": "Date this stint began, `YYYY-MM-DD`." }, "removed_at": { "type": [ "string", "null" ], "description": "Date this stint ended, `YYYY-MM-DD`; `null` for the currently-active stint." }, "position": { "type": [ "integer", "null" ], "description": "Last known position (1-based) during this stint." } }, "additionalProperties": false }, "description": "Add→remove cycles of the track on this playlist, oldest first, ending with the currently-active stint (`removed_at: null`) when the track is on the playlist. Capped at the most recent 100 cycles — compare with `total_stints`. Empty when `found` is false." }, "total_stints": { "type": "integer", "minimum": 0, "description": "Total number of stints the track has had on this playlist (including the active one), even when `stints` is capped." } }, "required": [ "found" ], "additionalProperties": false } }, "required": [ "obj" ], "additionalProperties": false }, "examples": { "default": { "value": { "obj": { "found": true, "span": "current", "position": 12, "peak_position": 4, "added_at": "2026-09-18", "removed_at": null, "followers": 914736, "playlist_type": { "editorial": true, "personalized": false, "fullyPersonalized": false, "chart": false, "thisIs": false, "newMusicFriday": false, "radio": false, "brand": false, "majorCurator": false, "popularIndie": false, "indie": false, "audiobook": false }, "stints": [ { "added_at": "2026-06-02", "removed_at": "2026-07-14", "position": 31 }, { "added_at": "2026-09-18", "removed_at": null, "position": 12 } ], "total_stints": 2 } } } } } } } } } }, "/api/playlist/by/{type}/{id}/evolution": { "get": { "summary": "Get Playlist Evolution by Artist, Album, or Track", "tags": [ "Playlist" ], "operationId": "getPlaylistEvolutionByEntity", "description": "Daily playlist-count and total-reach time series across six streaming platforms for the given entity (`artist`, `album`, or `track`). iTunes, Amazon, and SoundCloud only expose counts (no reach). Reach numbers can exceed the 32-bit range.", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer", "description": "Chartmetric metadata ID for the entity selected by `type` (artist, album, or track ID)." }, "required": true, "description": "Chartmetric metadata ID for the entity selected by `type` (artist, album, or track ID).", "examples": { "default": { "value": 1 } } }, { "name": "type", "in": "path", "schema": { "type": "string", "enum": [ "artist", "track", "album" ], "description": "Chartmetric metadata type. One of `artist`, `album`, or `track`." }, "required": true, "description": "Chartmetric metadata type. One of `artist`, `album`, or `track`.", "examples": { "default": { "value": "artist" } } }, { "name": "since", "in": "query", "schema": { "type": "string", "format": "date", "description": "Inclusive start of the date range in `YYYY-MM-DD` format. Defaults to 180 days before today.", "default": "2026-05-09" }, "required": false, "description": "Inclusive start of the date range in `YYYY-MM-DD` format. Defaults to 180 days before today." }, { "name": "until", "in": "query", "schema": { "type": "string", "format": "date", "description": "Inclusive end of the date range in `YYYY-MM-DD` format. Defaults to today.", "default": "2026-11-05" }, "required": false, "description": "Inclusive end of the date range in `YYYY-MM-DD` format. Defaults to today." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "anyOf": [ { "type": "object", "properties": { "spotify": { "type": "array", "items": { "type": "object", "properties": { "created_at": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Date the stats are recorded for (`YYYY-MM-DD`)." }, "playlist_count": { "type": [ "integer", "null" ], "description": "Total number of playlists containing the entity on this date." }, "ed_playlist_count": { "type": [ "integer", "null" ], "description": "Total number of editorial playlists containing the entity on this date." }, "playlist_total_reach": { "type": [ "integer", "null" ], "minimum": 0, "description": "Sum of follower/fan/subscriber counts across all playlists containing the entity on this date. May exceed the 32-bit range." }, "ed_playlist_total_reach": { "type": [ "integer", "null" ], "minimum": 0, "description": "Sum of follower/fan/subscriber counts across editorial playlists only. May exceed the 32-bit range." } } }, "description": "Daily playlist-count and reach time series for Spotify." }, "itunes": { "type": "array", "items": { "type": "object", "properties": { "created_at": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Date the stats are recorded for (`YYYY-MM-DD`)." }, "playlist_count": { "type": [ "integer", "null" ], "description": "Total number of playlists containing the entity on this date." }, "ed_playlist_count": { "type": [ "integer", "null" ], "description": "Total number of editorial playlists containing the entity on this date." } } }, "description": "Daily playlist-count time series for iTunes/Apple Music (no reach)." }, "deezer": { "type": "array", "items": { "type": "object", "properties": { "created_at": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Date the stats are recorded for (`YYYY-MM-DD`)." }, "playlist_count": { "type": [ "integer", "null" ], "description": "Total number of playlists containing the entity on this date." }, "ed_playlist_count": { "type": [ "integer", "null" ], "description": "Total number of editorial playlists containing the entity on this date." }, "playlist_total_reach": { "type": [ "integer", "null" ], "minimum": 0, "description": "Sum of follower/fan/subscriber counts across all playlists containing the entity on this date. May exceed the 32-bit range." }, "ed_playlist_total_reach": { "type": [ "integer", "null" ], "minimum": 0, "description": "Sum of follower/fan/subscriber counts across editorial playlists only. May exceed the 32-bit range." } } }, "description": "Daily playlist-count and reach time series for Deezer." }, "amazon": { "type": "array", "items": { "type": "object", "properties": { "created_at": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Date the stats are recorded for (`YYYY-MM-DD`)." }, "playlist_count": { "type": [ "integer", "null" ], "description": "Total number of playlists containing the entity on this date." }, "ed_playlist_count": { "type": [ "integer", "null" ], "description": "Total number of editorial playlists containing the entity on this date." } } }, "description": "Daily playlist-count time series for Amazon (no reach)." }, "youtube": { "type": "array", "items": { "type": "object", "properties": { "created_at": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Date the stats are recorded for (`YYYY-MM-DD`)." }, "playlist_count": { "type": [ "integer", "null" ], "description": "Total number of playlists containing the entity on this date." }, "ed_playlist_count": { "type": [ "integer", "null" ], "description": "Total number of editorial playlists containing the entity on this date." }, "playlist_total_reach": { "type": [ "integer", "null" ], "minimum": 0, "description": "Sum of follower/fan/subscriber counts across all playlists containing the entity on this date. May exceed the 32-bit range." }, "ed_playlist_total_reach": { "type": [ "integer", "null" ], "minimum": 0, "description": "Sum of follower/fan/subscriber counts across editorial playlists only. May exceed the 32-bit range." } } }, "description": "Daily playlist-count and reach time series for YouTube." }, "soundcloud": { "type": "array", "items": { "type": "object", "properties": { "created_at": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Date the stats are recorded for (`YYYY-MM-DD`)." }, "playlist_count": { "type": [ "integer", "null" ], "description": "Total number of playlists containing the entity on this date." }, "ed_playlist_count": { "type": [ "integer", "null" ], "description": "Total number of editorial playlists containing the entity on this date." } } }, "description": "Daily playlist-count time series for SoundCloud (no reach)." } }, "required": [ "spotify", "itunes", "deezer", "amazon", "youtube", "soundcloud" ] }, { "type": "object", "properties": {}, "additionalProperties": false } ] } }, "required": [ "obj" ], "additionalProperties": false }, "examples": { "default": { "value": { "obj": { "spotify": [ { "created_at": "2018-12-01", "playlist_count": 1095, "ed_playlist_count": 8, "playlist_total_reach": 4296113, "ed_playlist_total_reach": 3383510 } ], "amazon": [], "deezer": [], "youtube": [], "itunes": [ { "created_at": "2018-12-01", "playlist_count": 15, "ed_playlist_count": 3 } ], "soundcloud": [] } } } } } } } } } }, "/api/playlist/{platform}/{id}/journey-progression/{type}": { "get": { "summary": "Get Playlist Journey / Progression", "tags": [ "Playlist" ], "operationId": "getPlaylistJourneyProgress", "description": "Look-back (`journey`) or look-ahead (`progression`) analysis of playlists that share tracks with the target playlist over time.", "parameters": [ { "name": "platform", "in": "path", "schema": { "type": "string", "enum": [ "spotify", "applemusic", "deezer", "soundcloud" ], "description": "Streaming platform. One of `spotify`, `applemusic`, `deezer`, `soundcloud`." }, "required": true, "description": "Streaming platform. One of `spotify`, `applemusic`, `deezer`, `soundcloud`.", "examples": { "default": { "value": "spotify" } } }, { "name": "id", "in": "path", "schema": { "anyOf": [ { "type": "integer", "minimum": 0, "x-required": true }, { "type": "integer", "minimum": 0, "maximum": 2147483647, "x-required": true } ], "description": "Chartmetric playlist ID. Deezer uses bigInt IDs; other platforms use 32-bit integers." }, "required": true, "description": "Chartmetric playlist ID. Deezer uses bigInt IDs; other platforms use 32-bit integers.", "examples": { "default": { "value": 1 } } }, { "name": "type", "in": "path", "schema": { "type": "string", "enum": [ "journey", "progression" ], "description": "Look-back (`journey`) or look-ahead (`progression`) analysis of playlists that share tracks with the target." }, "required": true, "description": "Look-back (`journey`) or look-ahead (`progression`) analysis of playlists that share tracks with the target.", "examples": { "default": { "value": "journey" } } }, { "name": "sortColumn", "in": "query", "schema": { "type": "string", "enum": [ "overlap", "followers" ], "description": "Column to sort matched playlists by. One of `overlap` (total percent overlap) or `followers`. Defaults to `overlap`." }, "required": false, "description": "Column to sort matched playlists by. One of `overlap` (total percent overlap) or `followers`. Defaults to `overlap`." }, { "name": "sortOrderDesc", "in": "query", "schema": { "type": "boolean", "description": "If true, sort `sortColumn` in descending order. Defaults to true.", "default": true }, "required": false, "description": "If true, sort `sortColumn` in descending order. Defaults to true." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, "required": false, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "description": "Maximum number of items to return per request.", "default": 10 }, "required": false, "description": "Maximum number of items to return per request." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "object", "properties": { "total": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "nullable": true, "description": "Total number of matched playlists before pagination." }, "data": { "type": "array", "items": { "type": "object", "properties": { "plid": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Matched playlist ID (platform-native)." }, "name": { "type": [ "string", "null" ], "description": "Matched playlist name." }, "followers": { "type": [ "integer", "null" ], "minimum": 0, "description": "Current follower count of the matched playlist." }, "image_url": { "type": [ "string", "null" ], "description": "Cover image URL of the matched playlist." }, "total_percent_overlap": { "type": [ "number", "null" ], "format": "float", "description": "Total track overlap between target and matched playlist as a fraction (0–1)." }, "count_distinct_tracks": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "nullable": true, "description": "Number of distinct tracks shared between target and matched playlist." }, "events": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "days": { "type": [ "integer", "null" ], "description": "Number of days between the matched-playlist event and the target playlist event." }, "day_percent_overlap": { "type": [ "number", "null" ], "format": "float", "description": "Track overlap between target and matched playlist on this day, as a fraction (0–1)." }, "tracks_added": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric track ID for the added track." }, "name": { "type": [ "string", "null" ], "description": "Track name." }, "image_url": { "type": [ "string", "null" ], "description": "Album cover image URL." }, "isrc": { "type": [ "string", "null" ], "description": "International Standard Recording Code (ISRC) of the track." } } }, "description": "Tracks added during this event window." } } }, "description": "Per-day overlap events between target and matched playlist." } } }, "description": "List of matched playlists with overlap details." } }, "required": [ "data" ] } }, "additionalProperties": false }, "examples": { "default": { "value": { "obj": { "total": "24", "data": [ { "plid": "1280262301", "name": "", "followers": 1022, "image_url": null, "total_percent_overlap": 0.055556, "count_distinct_tracks": "2", "events": [ { "days": 16, "day_percent_overlap": 0.055556, "tracks_added": [ { "id": 20654220, "name": "Flou", "image_url": "https://is3-ssl.mzstatic.com/image/thumb/Music118/v4/4f/a7/07/4fa707be-69f1-e04a-cf70-164918eb8fb2/source/160x160bb.jpeg", "isrc": "BE8HB1800014" } ] } ] } ] } } } } } } } } } }, "/api/playlist/{platform}/{id}/updated": { "get": { "summary": "Get Playlist Last Updated Time", "tags": [ "Playlist" ], "operationId": "getPlaylistLastUpdated", "description": "Return the last time the playlist itself was observed updated by Chartmetric, and the most recent track add/removal events. For Spotify, also includes `tracks_last_updated` from the ClickHouse cache.", "parameters": [ { "name": "platform", "in": "path", "schema": { "type": "string", "enum": [ "spotify", "itunes", "applemusic", "deezer", "amazon", "youtube", "boomplay", "soundcloud" ], "description": "Streaming platform. One of `spotify`, `itunes`/`applemusic`, `deezer`, `amazon`, `youtube`, `boomplay`, `soundcloud`." }, "required": true, "description": "Streaming platform. One of `spotify`, `itunes`/`applemusic`, `deezer`, `amazon`, `youtube`, `boomplay`, `soundcloud`.", "examples": { "default": { "value": "spotify" } } }, { "name": "id", "in": "path", "schema": { "anyOf": [ { "type": "integer", "x-required": true }, { "type": "string", "pattern": "^\\d+$", "x-required": true }, { "type": "string", "x-required": true } ], "description": "Chartmetric playlist ID. Numeric for `spotify`/`itunes`/`applemusic`/`boomplay`; numeric string (bigInt) for `deezer`; string for `amazon`/`youtube`." }, "required": true, "description": "Chartmetric playlist ID. Numeric for `spotify`/`itunes`/`applemusic`/`boomplay`; numeric string (bigInt) for `deezer`; string for `amazon`/`youtube`.", "examples": { "default": { "value": 1 } } }, { "name": "storefront", "in": "query", "schema": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB')." }, "required": false, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB')." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": [ "object", "null" ], "properties": { "sys_last_updated": { "anyOf": [ { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Date when Chartmetric last refreshed the playlist and its stats." }, "playlist_last_updated": { "anyOf": [ { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Date when a track was last added to or removed from the playlist." }, "last_added": { "anyOf": [ { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Date when a track was last added to the playlist." }, "last_removed": { "anyOf": [ { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Date when a track was last removed from the playlist." }, "tracks_last_updated": { "anyOf": [ { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Date the ClickHouse tracks cache was last refreshed for the playlist (Spotify only)." } } } }, "additionalProperties": false }, "examples": { "default": { "value": { "obj": { "sys_last_updated": "2022-07-28T00:00:00.000Z", "last_added": "2022-07-22T00:04:38.539Z", "last_removed": "2022-07-22T00:04:41.687Z" } } } } } } } } } }, "/api/radio/{type}/{id}/airplay-totals": { "get": { "summary": "Total Airplays", "tags": [ "Radio" ], "operationId": "getRadioAirplayTotals", "description": "Returns total airplay counts grouped by country, city, station, and track for the given `artist`, `album`, or `track`. **Deprecated** — prefer `GET /api/radio/{type}/{id}/airplay-totals/{entity}` for per-entity pagination.", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric ID for the entity in `:type` (artist / album / track ID)." }, "required": true, "description": "Chartmetric ID for the entity in `:type` (artist / album / track ID).", "examples": { "default": { "value": 1 } } }, { "name": "type", "in": "path", "schema": { "type": "string", "enum": [ "artist", "track", "album" ], "description": "Entity kind that `:id` refers to (one of `artist | album | track`)." }, "required": true, "description": "Entity kind that `:id` refers to (one of `artist | album | track`).", "examples": { "default": { "value": "artist" } } }, { "name": "since", "in": "query", "schema": { "type": "string", "format": "date", "description": "Start date for aggregating airplay totals in ISO format (e.g. `2025-11-01`); defaults to 180 days ago.", "default": "2026-05-09" }, "required": true, "description": "Start date for aggregating airplay totals in ISO format (e.g. `2025-11-01`); defaults to 180 days ago.", "examples": { "default": { "value": "2026-05-09" } } }, { "name": "station", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric radio station ID; when set, narrows results to plays on this station only." }, "required": false, "description": "Chartmetric radio station ID; when set, narrows results to plays on this station only." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum entries returned per group (countries/cities/stations/tracks).", "default": 10 }, "required": false, "description": "Maximum entries returned per group (countries/cities/stations/tracks)." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "object", "properties": { "countries": { "type": "array", "items": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "code2": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB')." }, "name": { "type": [ "string", "null" ], "description": "Country name." }, "plays": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "description": "Total airplays in this country across the requested period." }, "plays_percent": { "type": "number", "format": "float", "description": "Country's share of total airplays as a fraction in [0, 1]." }, "station_count": { "type": "integer", "description": "Distinct stations in this country that aired the entity. Omitted for `track`." }, "top_station_name": { "type": [ "string", "null" ], "description": "Name of the top-airing station in this country. Omitted for `track`." } }, "required": [ "code2", "name", "plays", "plays_percent" ] }, { "type": "array", "items": { "type": "object", "properties": { "air_date": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "description": "Date of the play count bucket. ISO 8601 string by default; UTC epoch seconds when `dateFormat=UNIX`." }, "count": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "description": "Number of spins on `air_date`. May be a numeric string from Postgres aggregates." } }, "required": [ "air_date", "count" ] } } ] }, "minItems": 2, "maxItems": 2 }, "description": "Per-country airplay totals as `[infoObject, trendsArray]` tuples." }, "cities": { "type": "array", "items": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric city ID." }, "name": { "type": [ "string", "null" ], "description": "City name." }, "code2": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB')." }, "country": { "type": [ "string", "null" ], "description": "Country name of the city." }, "lat": { "type": [ "number", "null" ], "format": "float", "description": "City latitude in decimal degrees." }, "lng": { "type": [ "number", "null" ], "format": "float", "description": "City longitude in decimal degrees." }, "plays": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "description": "Total airplays in this city across the requested period." }, "plays_percent": { "type": "number", "format": "float", "description": "City's share of total airplays as a fraction in [0, 1]." }, "station_count": { "type": "integer", "description": "Distinct stations in this city that aired the entity. Omitted for `track`." }, "top_station_name": { "type": [ "string", "null" ], "description": "Name of the top-airing station in this city. Omitted for `track`." } }, "required": [ "id", "name", "code2", "country", "lat", "lng", "plays", "plays_percent" ] }, { "type": "array", "items": { "type": "object", "properties": { "air_date": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "description": "Date of the play count bucket. ISO 8601 string by default; UTC epoch seconds when `dateFormat=UNIX`." }, "count": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "description": "Number of spins on `air_date`. May be a numeric string from Postgres aggregates." } }, "required": [ "air_date", "count" ] } } ] }, "minItems": 2, "maxItems": 2 }, "description": "Per-city airplay totals as `[infoObject, trendsArray]` tuples." }, "stations": { "type": "array", "items": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric radio station ID." }, "name": { "type": [ "string", "null" ], "description": "Radio station name." }, "code2": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code where the station broadcasts." }, "city": { "type": [ "string", "null" ], "description": "City the station broadcasts from." }, "country": { "type": [ "string", "null" ], "description": "Country the station broadcasts from." }, "plays": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "description": "Total airplays on this station across the requested period." }, "plays_percent": { "type": "number", "format": "float", "description": "Station's share of total airplays as a fraction in [0, 1]." } }, "required": [ "id", "name", "code2", "city", "country", "plays", "plays_percent" ] }, { "type": "array", "items": { "type": "object", "properties": { "air_date": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "description": "Date of the play count bucket. ISO 8601 string by default; UTC epoch seconds when `dateFormat=UNIX`." }, "count": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "description": "Number of spins on `air_date`. May be a numeric string from Postgres aggregates." } }, "required": [ "air_date", "count" ] } } ] }, "minItems": 2, "maxItems": 2 }, "description": "Per-station airplay totals as `[infoObject, trendsArray]` tuples." }, "tracks": { "type": "array", "items": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric track ID." }, "name": { "type": [ "string", "null" ], "description": "Track title." }, "isrc": { "type": [ "string", "null" ], "description": "International Standard Recording Code of the track." }, "plays": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "description": "Total airplays for this track across the requested period." }, "plays_percent": { "type": "number", "format": "float", "description": "Track's share of total airplays as a fraction in [0, 1]." }, "station_count": { "type": "integer", "description": "Distinct stations that aired this track. Returned for artist/album scopes." }, "top_station_name": { "type": [ "string", "null" ], "description": "Name of the top-airing station for this track. Returned for artist/album scopes." } }, "required": [ "id", "name", "isrc", "plays", "plays_percent" ] }, { "type": "array", "items": { "type": "object", "properties": { "air_date": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "description": "Date of the play count bucket. ISO 8601 string by default; UTC epoch seconds when `dateFormat=UNIX`." }, "count": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "description": "Number of spins on `air_date`. May be a numeric string from Postgres aggregates." } }, "required": [ "air_date", "count" ] } } ] }, "minItems": 2, "maxItems": 2 }, "description": "Per-track airplay totals as `[infoObject, trendsArray]` tuples. Returned for artist/album scopes." } }, "required": [ "countries", "cities", "stations", "tracks" ] } }, "required": [ "obj" ], "additionalProperties": false }, "examples": { "default": { "value": { "obj": { "countries": [ [ { "code2": "US", "name": "United States", "plays": 76376, "plays_percent": 0.43664886744342934 }, [ { "air_date": "2023-01-01T00:00:00.000Z", "count": 932 }, { "air_date": "2023-01-02T00:00:00.000Z", "count": 924 } ] ] ], "cities": [ [ { "id": 2698, "name": "Berlin", "code2": "DE", "country": "Germany", "lat": 52.5218, "lng": 13.4015, "plays": 6168, "plays_percent": 0.03526304355283168 }, [ { "air_date": "2023-01-01T00:00:00.000Z", "count": 89 } ] ] ], "stations": [ [ { "id": 196100, "name": "ENERGY Romantic", "code2": "DE", "city": "Berlin", "country": "Germany", "plays": 1772, "plays_percent": 0.010130692797603393 }, [ { "air_date": "2023-01-01T00:00:00.000Z", "count": 22 } ] ] ], "tracks": [ [ { "id": 63926722, "name": "Easy On Me", "isrc": "USSM12105970", "plays": 44623, "plays_percent": 0.25511394170849677 }, [ { "air_date": "2023-01-01T00:00:00.000Z", "count": 703 } ] ] ] } } } } } } } } } }, "/api/radio/{type}/{id}/airplay-totals/{entity}": { "get": { "summary": "Total Airplays by Entity", "tags": [ "Radio" ], "operationId": "getRadioAirplayTotalsByEntity", "description": "Returns airplay counts for the given `:type` (`artist`, `album`, `track`), grouped by the requested `:entity` (`country`, `city`, `station`, `track`). Each item includes a `plays_trend` time series.", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric ID for the entity in `:type` (artist / album / track ID)." }, "required": true, "description": "Chartmetric ID for the entity in `:type` (artist / album / track ID).", "examples": { "default": { "value": 1 } } }, { "name": "type", "in": "path", "schema": { "type": "string", "enum": [ "artist", "track", "album" ], "description": "Entity kind that `:id` refers to (one of `artist | album | track`)." }, "required": true, "description": "Entity kind that `:id` refers to (one of `artist | album | track`).", "examples": { "default": { "value": "artist" } } }, { "name": "entity", "in": "path", "schema": { "type": "string", "enum": [ "country", "city", "station", "track" ], "description": "Grouping dimension for airplay totals (one of `country | city | station | track`)." }, "required": true, "description": "Grouping dimension for airplay totals (one of `country | city | station | track`).", "examples": { "default": { "value": "country" } } }, { "name": "since", "in": "query", "schema": { "type": "string", "format": "date", "description": "Start date for aggregating airplay totals in ISO format (e.g. `2025-11-01`); defaults to 180 days ago.", "default": "2026-05-09" }, "required": true, "description": "Start date for aggregating airplay totals in ISO format (e.g. `2025-11-01`); defaults to 180 days ago.", "examples": { "default": { "value": "2026-05-09" } } }, { "name": "station", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric radio station ID; when set, restricts play counts to a single station." }, "required": false, "description": "Chartmetric radio station ID; when set, restricts play counts to a single station." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum entries returned in the `:entity` grouping.", "default": 10 }, "required": false, "description": "Maximum entries returned in the `:entity` grouping." }, { "name": "dateFormat", "in": "query", "schema": { "type": "string", "enum": [ "ISO", "UNIX" ], "description": "Format of `air_date` in `plays_trend` items: `ISO` for ISO 8601 strings, `UNIX` for UTC epoch seconds.", "default": "ISO" }, "required": false, "description": "Format of `air_date` in `plays_trend` items: `ISO` for ISO 8601 strings, `UNIX` for UTC epoch seconds." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "array", "items": { "type": "object", "properties": { "code2": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code (e.g. 'US'). Present when `:entity` is `country`, `city`, or `station`." }, "id": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric ID of the city / station / track. Present when `:entity` is `city`, `station`, or `track`." }, "name": { "type": [ "string", "null" ], "description": "Display name of the country / city / station / track." }, "country": { "type": [ "string", "null" ], "description": "Country name. Present when `:entity` is `city` or `station`." }, "lat": { "type": [ "number", "null" ], "format": "float", "description": "Latitude in decimal degrees. Present when `:entity` is `city`." }, "lng": { "type": [ "number", "null" ], "format": "float", "description": "Longitude in decimal degrees. Present when `:entity` is `city`." }, "city": { "type": [ "string", "null" ], "description": "City the station broadcasts from. Present when `:entity` is `station`." }, "isrc": { "type": [ "string", "null" ], "description": "International Standard Recording Code. Present when `:entity` is `track`." }, "plays": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "description": "Total airplays for this entity across the requested period." }, "plays_percent": { "type": "number", "format": "float", "description": "Entity's share of total airplays as a fraction in [0, 1]." }, "plays_trend": { "type": "array", "items": { "type": "object", "properties": { "air_date": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "description": "Date of the play count bucket. ISO 8601 string by default; UTC epoch seconds when `dateFormat=UNIX`." }, "count": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "description": "Number of spins on `air_date`. May be a numeric string from Postgres aggregates." } }, "required": [ "air_date", "count" ] }, "description": "Per-day play counts for this entity over the requested period." } }, "required": [ "plays", "plays_percent", "plays_trend" ] } } }, "required": [ "obj" ], "additionalProperties": false }, "examples": { "default": { "value": { "obj": [ { "code2": "US", "name": "United States", "plays": 81275, "plays_percent": 0.43441659094553425, "plays_trend": [ { "air_date": "2023-01-01", "count": 916 } ] } ] } } } } } } } } }, "/api/radio/{type}/{id}/airplays": { "get": { "summary": "Airplay information in Time Series", "tags": [ "Radio" ], "operationId": "getRadioAirplays", "description": "Time series of how many times an `artist`, `album`, or `track` played on the radio. `air_date` is returned as a UNIX-epoch-milliseconds timestamp.", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric ID for the entity in `:type` (artist / album / track ID)." }, "required": true, "description": "Chartmetric ID for the entity in `:type` (artist / album / track ID).", "examples": { "default": { "value": 1 } } }, { "name": "type", "in": "path", "schema": { "type": "string", "enum": [ "artist", "track", "album" ], "description": "Entity kind that `:id` refers to (one of `artist | album | track`)." }, "required": true, "description": "Entity kind that `:id` refers to (one of `artist | album | track`).", "examples": { "default": { "value": "artist" } } }, { "name": "since", "in": "query", "schema": { "type": "string", "format": "date", "description": "Start date of the time series in ISO format (e.g. `2025-11-01`); defaults to 180 days ago.", "default": "2026-05-09" }, "required": true, "description": "Start date of the time series in ISO format (e.g. `2025-11-01`); defaults to 180 days ago.", "examples": { "default": { "value": "2026-05-09" } } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "array", "items": { "type": "object", "properties": { "air_date": { "type": "integer", "minimum": 0, "description": "Timestamp of the day bucket as a UTC Unix epoch in milliseconds." }, "spins": { "type": "integer", "minimum": 0, "description": "Number of plays (spins) recorded on `air_date`." } }, "required": [ "air_date", "spins" ] } } }, "required": [ "obj" ], "additionalProperties": false }, "examples": { "default": { "value": { "obj": [ { "air_date": 1665964800000, "spins": 6 }, { "air_date": 1666051200000, "spins": 7 } ] } } } } } } } } }, "/api/radio/{type}/{id}/broadcast-markets": { "get": { "summary": "Broadcast Market play counts", "tags": [ "Radio" ], "operationId": "getRadioBroadcastMarkets", "description": "Returns play counts per broadcast market (country and city) for an `artist`, `album`, or `track`. Aggregate counts come from Postgres and are returned as decimal strings.", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric ID for the entity in `:type` (artist / album / track ID)." }, "required": true, "description": "Chartmetric ID for the entity in `:type` (artist / album / track ID).", "examples": { "default": { "value": 1 } } }, { "name": "type", "in": "path", "schema": { "type": "string", "enum": [ "artist", "track", "album" ], "description": "Entity kind that `:id` refers to (one of `artist | album | track`)." }, "required": true, "description": "Entity kind that `:id` refers to (one of `artist | album | track`).", "examples": { "default": { "value": "artist" } } }, { "name": "since", "in": "query", "schema": { "type": "string", "format": "date", "description": "Start date for aggregating broadcast-market play counts in ISO format (e.g. `2025-11-01`); defaults to 180 days ago.", "default": "2026-05-09" }, "required": true, "description": "Start date for aggregating broadcast-market play counts in ISO format (e.g. `2025-11-01`); defaults to 180 days ago.", "examples": { "default": { "value": "2026-05-09" } } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "object", "properties": { "countryRatios": { "type": "array", "items": { "type": "object", "properties": { "market": { "type": [ "string", "null" ], "description": "Country market name." }, "market_count_data": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "description": "Total airplays for the entity in this country market." }, "code2": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB')." }, "total_market_count_data": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Total airplays in this market across all entities (denominator used to compute `count`)." }, "count_of_stations": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "description": "Number of distinct stations contributing to this market." }, "population": { "type": [ "number", "null" ], "format": "float", "description": "Estimated population of the country market." }, "lat": { "type": [ "number", "null" ], "format": "float", "description": "Country centroid latitude in decimal degrees." }, "lng": { "type": [ "number", "null" ], "format": "float", "description": "Country centroid longitude in decimal degrees." }, "count": { "type": "number", "format": "float", "description": "Per-capita play intensity: airplays per 10k population in this market (entity's market share scaled by population)." } }, "required": [ "market", "market_count_data", "code2", "total_market_count_data", "count_of_stations", "population", "lat", "lng", "count" ] }, "description": "Country-level broadcast market entries with airplay counts and station coverage." }, "cityRatios": { "type": "array", "items": { "type": "object", "properties": { "market": { "type": [ "string", "null" ], "description": "City market name." }, "display_name": { "type": [ "string", "null" ], "description": "Human-readable market label (e.g. 'Dayton (United States)')." }, "code2": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB')." }, "market_count_data": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "description": "Total airplays for the entity in this city market." }, "country": { "type": [ "string", "null" ], "description": "Country name of the city." }, "total_market_count_data": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "nullable": true, "description": "Total airplays in this market across all entities (denominator used to compute `count`)." }, "count_of_stations": { "anyOf": [ { "type": "string" }, { "type": "number", "format": "float" } ], "description": "Number of distinct stations contributing to this city market." }, "city_id": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric city ID." }, "population": { "type": [ "number", "null" ], "format": "float", "description": "Estimated population of the city." }, "lat": { "type": [ "number", "null" ], "format": "float", "description": "City latitude in decimal degrees." }, "lng": { "type": [ "number", "null" ], "format": "float", "description": "City longitude in decimal degrees." }, "count": { "type": "number", "format": "float", "description": "Per-capita play intensity: airplays per 10k population in this market (entity's market share scaled by population)." } }, "required": [ "market", "display_name", "code2", "market_count_data", "country", "total_market_count_data", "count_of_stations", "city_id", "population", "lat", "lng", "count" ] }, "description": "City-level broadcast market entries with airplay counts and station coverage." } }, "required": [ "countryRatios", "cityRatios" ] } }, "required": [ "obj" ], "additionalProperties": false }, "examples": { "default": { "value": { "obj": { "countryRatios": [ { "market": "Malaysia", "market_count_data": "1155", "code2": "MY", "total_market_count_data": "63226", "count_of_stations": "5", "population": 22244000, "lat": 4.210484, "lng": 101.975766, "count": 1.82678012210167 } ], "cityRatios": [ { "market": "Dayton", "display_name": "Dayton (United States)", "code2": "US", "market_count_data": "300", "country": "United States", "total_market_count_data": "9778", "count_of_stations": "1", "city_id": 6869, "population": 5449, "lat": 39.1128, "lng": -84.464, "count": 3.06811208836163 } ] } } } } } } } } } }, "/api/radio/station-list": { "get": { "summary": "Get Radio Station List for Country", "tags": [ "Radio" ], "operationId": "listRadioStations", "description": "Returns the list of stations along with metadata for a given country (2-letter code). Station social-media counts come from a LEFT JOIN and may be null.", "parameters": [ { "name": "code2", "in": "query", "schema": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB')." }, "required": false, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB')." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric radio station ID." }, "name": { "type": [ "string", "null" ], "description": "Station callsign or display name." }, "genre": { "type": [ "string", "null" ], "description": "Station format / genre (e.g. 'Hot AC', 'News/Talk')." }, "frequency": { "type": [ "string", "null" ], "description": "Dial position (e.g. `104.3` for FM, `1010` for AM)." }, "market": { "type": [ "string", "null" ], "description": "Primary broadcast market the station serves." }, "broadcast_area": { "type": [ "string", "null" ], "description": "Geographic area covered by the station signal." }, "country": { "type": [ "string", "null" ], "description": "Country the station broadcasts from." }, "station_state": { "type": [ "string", "null" ], "description": "Two-letter state or province code (e.g. `CA`, `NY`)." }, "image_url": { "type": [ "string", "null" ], "description": "URL of the station logo or image asset." }, "aqh": { "type": [ "integer", "null" ], "description": "Average Quarter-Hour persons: unique listeners tuning in for >5 minutes within a 15-minute window. Available for US stations only." }, "platform": { "type": [ "string", "null" ], "description": "Distribution platform of the station (e.g. 'Terrestrial', 'Satellite', 'Online')." }, "facebook_followers": { "type": [ "integer", "null" ], "description": "Followers on the station's Facebook page. Null when the station has no linked Facebook account." }, "facebook_likes": { "type": [ "integer", "null" ], "description": "Likes on the station's Facebook page. Null when the station has no linked Facebook account." }, "instagram_followers": { "type": [ "integer", "null" ], "description": "Followers on the station's Instagram account. Null when the station has no linked Instagram account." }, "twitter_followers": { "type": [ "integer", "null" ], "description": "Followers on the station's Twitter/X account. Null when the station has no linked Twitter account." }, "wikipedia_views": { "type": [ "integer", "null" ], "description": "Pageviews on the station's Wikipedia article. Null when the station has no linked Wikipedia page." } }, "required": [ "id", "name" ] } } }, "required": [ "obj" ], "additionalProperties": false }, "examples": { "default": { "value": { "obj": [ { "id": 214403, "name": "KBIG 104.3 MYfm", "genre": "Hot AC", "frequency": "104.3", "market": "Los Angeles", "broadcast_area": "Los Angeles", "country": "United States", "station_state": "CA", "image_url": "https://storage.googleapis.com/cm-app-assets/radio-images/2627_KBIG_FM.png", "aqh": 65700, "platform": "Terrestrial", "facebook_followers": null, "facebook_likes": null, "instagram_followers": 33094, "twitter_followers": 27228, "wikipedia_views": 44 } ] } } } } } } } } }, "/api/track/playlist-stream-estimates": { "post": { "summary": "Get Batch Playlist Stream Estimates", "tags": [ "Track" ], "operationId": "getBatchPlaylistStreamEstimates", "description": "Return per-track availability and playlist stream estimates for a batch of track IDs. Missing tracks are returned with `status: \"not_found\"` rather than failing the whole request.", "parameters": [ { "name": "date", "in": "query", "schema": { "type": "string", "format": "date", "description": "Snapshot date in YYYY-MM-DD format. Mutually exclusive with `since`/`until`. Omit all of `date`/`since`/`until` to get the latest available snapshot." }, "required": false, "description": "Snapshot date in YYYY-MM-DD format. Mutually exclusive with `since`/`until`. Omit all of `date`/`since`/`until` to get the latest available snapshot." }, { "name": "since", "in": "query", "schema": { "type": "string", "format": "date", "description": "Start of the weekly snapshot history range in YYYY-MM-DD format." }, "required": false, "description": "Start of the weekly snapshot history range in YYYY-MM-DD format." }, { "name": "until", "in": "query", "schema": { "type": "string", "format": "date", "description": "End of the weekly snapshot history range in YYYY-MM-DD format." }, "required": false, "description": "End of the weekly snapshot history range in YYYY-MM-DD format." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "minItems": 1, "maxItems": 50, "uniqueItems": true, "description": "One or more Chartmetric track IDs.", "examples": [ [ 1 ] ] } }, "required": [ "ids" ], "additionalProperties": false, "examples": [ { "ids": [ 1 ] } ] }, "examples": { "default": { "value": { "ids": [ 1 ] } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "array", "items": { "type": "object", "properties": { "cm_track": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "status": { "type": "string", "enum": [ "available", "not_found" ] }, "estimates": { "type": "array", "items": { "type": "object", "properties": { "cm_track": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric track ID." }, "timestp": { "type": "string", "description": "Weekly snapshot date in YYYY-MM-DD format." }, "playlist_stream_pct": { "type": "number", "format": "float", "minimum": 0, "maximum": 100, "description": "Estimated percentage of streams generated by playlists." }, "playlist_count": { "type": "integer", "minimum": 0, "description": "Number of playlists contributing." }, "expected_playlist_streams": { "type": "number", "format": "float", "minimum": 0, "description": "Estimated streams generated by playlists." }, "streams_gained_in_period": { "type": "number", "format": "float", "minimum": 0, "description": "Spotify streams gained during the trailing 28-day model window." }, "expected_editorial": { "type": "number", "format": "float", "minimum": 0, "description": "Estimated editorial playlist streams." }, "expected_chart": { "type": "number", "format": "float", "minimum": 0, "description": "Estimated chart playlist streams." }, "expected_user_other": { "type": "number", "format": "float", "minimum": 0, "description": "Estimated user and other playlist streams." } }, "required": [ "cm_track", "timestp", "playlist_stream_pct", "playlist_count", "expected_playlist_streams", "streams_gained_in_period", "expected_editorial", "expected_chart", "expected_user_other" ], "additionalProperties": false } } }, "required": [ "cm_track", "status", "estimates" ], "additionalProperties": false } } }, "required": [ "obj" ], "additionalProperties": false }, "examples": { "default": { "value": { "obj": [ { "cm_track": 141777092, "status": "available", "estimates": [ { "cm_track": 141777092, "timestp": "2026-07-11", "playlist_stream_pct": 58.11359808113311, "playlist_count": 17982, "expected_playlist_streams": 203672324, "streams_gained_in_period": 72672055, "expected_editorial": 113511005, "expected_chart": 12482763, "expected_user_other": 77678556 } ] } ] } } } } } } } } }, "/api/track/{id}/playlist-stream-estimates": { "get": { "summary": "Get Playlist Stream Estimates", "tags": [ "Track" ], "operationId": "getTrackPlaylistStreamEstimates", "description": "Return the latest weekly snapshot for a track when no query params are supplied, one requested snapshot via `date`, or all weekly snapshots in a `since`/`until` range. Each row describes a trailing 28-day estimate as of its snapshot date. Returns 404 when no matching snapshot exists — this table is populated incrementally, so a 404 here does not necessarily mean the track ID is invalid. The message distinguishes the two cases: an unfiltered request (no `date`/`since`/`until`) reports the track has no estimate computed yet at all, while a filtered request reports only that nothing matches the requested date or range (the track may still have estimates outside it).", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "required": true, "examples": { "default": { "value": 1 } } }, { "name": "date", "in": "query", "schema": { "type": "string", "format": "date", "description": "Snapshot date in YYYY-MM-DD format. Mutually exclusive with `since`/`until`. Omit all of `date`/`since`/`until` to get the latest available snapshot." }, "required": false, "description": "Snapshot date in YYYY-MM-DD format. Mutually exclusive with `since`/`until`. Omit all of `date`/`since`/`until` to get the latest available snapshot." }, { "name": "since", "in": "query", "schema": { "type": "string", "format": "date", "description": "Start of the weekly snapshot history range in YYYY-MM-DD format." }, "required": false, "description": "Start of the weekly snapshot history range in YYYY-MM-DD format." }, { "name": "until", "in": "query", "schema": { "type": "string", "format": "date", "description": "End of the weekly snapshot history range in YYYY-MM-DD format." }, "required": false, "description": "End of the weekly snapshot history range in YYYY-MM-DD format." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "anyOf": [ { "type": "object", "properties": { "cm_track": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric track ID." }, "timestp": { "type": "string", "description": "Weekly snapshot date in YYYY-MM-DD format." }, "playlist_stream_pct": { "type": "number", "format": "float", "minimum": 0, "maximum": 100, "description": "Estimated percentage of streams generated by playlists." }, "playlist_count": { "type": "integer", "minimum": 0, "description": "Number of playlists contributing." }, "expected_playlist_streams": { "type": "number", "format": "float", "minimum": 0, "description": "Estimated streams generated by playlists." }, "streams_gained_in_period": { "type": "number", "format": "float", "minimum": 0, "description": "Spotify streams gained during the trailing 28-day model window." }, "expected_editorial": { "type": "number", "format": "float", "minimum": 0, "description": "Estimated editorial playlist streams." }, "expected_chart": { "type": "number", "format": "float", "minimum": 0, "description": "Estimated chart playlist streams." }, "expected_user_other": { "type": "number", "format": "float", "minimum": 0, "description": "Estimated user and other playlist streams." } }, "required": [ "cm_track", "timestp", "playlist_stream_pct", "playlist_count", "expected_playlist_streams", "streams_gained_in_period", "expected_editorial", "expected_chart", "expected_user_other" ], "additionalProperties": false }, { "type": "array", "items": { "type": "object", "properties": { "cm_track": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric track ID." }, "timestp": { "type": "string", "description": "Weekly snapshot date in YYYY-MM-DD format." }, "playlist_stream_pct": { "type": "number", "format": "float", "minimum": 0, "maximum": 100, "description": "Estimated percentage of streams generated by playlists." }, "playlist_count": { "type": "integer", "minimum": 0, "description": "Number of playlists contributing." }, "expected_playlist_streams": { "type": "number", "format": "float", "minimum": 0, "description": "Estimated streams generated by playlists." }, "streams_gained_in_period": { "type": "number", "format": "float", "minimum": 0, "description": "Spotify streams gained during the trailing 28-day model window." }, "expected_editorial": { "type": "number", "format": "float", "minimum": 0, "description": "Estimated editorial playlist streams." }, "expected_chart": { "type": "number", "format": "float", "minimum": 0, "description": "Estimated chart playlist streams." }, "expected_user_other": { "type": "number", "format": "float", "minimum": 0, "description": "Estimated user and other playlist streams." } }, "required": [ "cm_track", "timestp", "playlist_stream_pct", "playlist_count", "expected_playlist_streams", "streams_gained_in_period", "expected_editorial", "expected_chart", "expected_user_other" ], "additionalProperties": false } } ] } }, "required": [ "obj" ], "additionalProperties": false }, "examples": { "default": { "value": { "obj": { "cm_track": 141777092, "timestp": "2026-07-11", "playlist_stream_pct": 58.11359808113311, "playlist_count": 17982, "expected_playlist_streams": 203672324, "streams_gained_in_period": 72672055, "expected_editorial": 113511005, "expected_chart": 12482763, "expected_user_other": 77678556 } } } } } } } } } }, "/api/track/{id}/video-trends": { "get": { "summary": "Get TikTok Video Trends for a Track", "tags": [ "Track" ], "operationId": "getTrackVideoTrends", "description": "Return the history of likes, comments, and views for a TikTok video over time. `id` here is a TikTok video internal ID, not a Chartmetric track ID.", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer", "minimum": 0, "description": "TikTok video internal ID (not a Chartmetric track ID). Identifies the specific video to retrieve trends for." }, "required": true, "description": "TikTok video internal ID (not a Chartmetric track ID). Identifies the specific video to retrieve trends for.", "examples": { "default": { "value": 1 } } }, { "name": "fromDaysAgo", "in": "query", "schema": { "type": "integer", "description": "Number of days before today at which the trend window starts. Defaults to 28.", "default": 28 }, "required": false, "description": "Number of days before today at which the trend window starts. Defaults to 28." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "array", "items": { "type": "object", "properties": { "timestp": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp of the data point in ISO-8601 form." }, "likes": { "type": [ "integer", "null" ], "description": "Cumulative likes count at this timestamp." }, "comments": { "type": [ "integer", "null" ], "description": "Cumulative comments count at this timestamp." }, "views": { "type": [ "integer", "null" ], "description": "Cumulative views count at this timestamp." } } } } }, "required": [ "obj" ], "additionalProperties": false }, "examples": { "default": { "value": { "obj": [ { "timestp": "2023-05-30T00:00:00.000Z", "likes": 72500, "comments": 222, "views": 411800 } ] } } } } } } } } }, "/api/track/{id}/{type}/charts": { "get": { "summary": "List Chart Appearances for a Track", "tags": [ "Track" ], "operationId": "listTrackCharts", "description": "Return chart records for this track across the supported platforms: Spotify (`spotify_viral_daily`, `spotify_viral_weekly`, `spotify_top_daily`, `spotify_top_weekly`), Apple Music (`applemusic_top`, `applemusic_daily`, `applemusic_albums`), iTunes (`itunes_top`, `itunes_albums`), Airplay (`airplay_daily`, `airplay_weekly`), Amazon, Shazam, Beatport, and SoundCloud.", "parameters": [ { "name": "type", "in": "path", "schema": { "type": "string", "enum": [ "spotify_viral_daily", "spotify_viral_weekly", "spotify_top_daily", "spotify_top_weekly", "applemusic_top", "applemusic_daily", "applemusic_albums", "itunes_top", "itunes_albums", "shazam", "beatport", "youtube", "youtube_tracks", "youtube_videos", "youtube_trends", "amazon", "soundcloud", "airplay_weekly", "airplay_daily" ], "description": "Chart variant to fetch. Combines platform with chart family/duration (e.g. `spotify_top_daily`, `applemusic_albums`, `airplay_weekly`, `shazam`, `amazon`)." }, "required": true, "description": "Chart variant to fetch. Combines platform with chart family/duration (e.g. `spotify_top_daily`, `applemusic_albums`, `airplay_weekly`, `shazam`, `amazon`).", "examples": { "default": { "value": "spotify_viral_daily" } } }, { "name": "id", "in": "path", "schema": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric track ID." }, "required": true, "description": "Chartmetric track ID.", "examples": { "default": { "value": 1 } } }, { "name": "since", "in": "query", "schema": { "type": "string", "format": "date", "description": "Inclusive start date for the chart window in `YYYY-MM-DD` format. Defaults to 180 days before today.", "default": "2026-05-09" }, "required": true, "description": "Inclusive start date for the chart window in `YYYY-MM-DD` format. Defaults to 180 days before today.", "examples": { "default": { "value": "2026-05-09" } } }, { "name": "until", "in": "query", "schema": { "type": "string", "format": "date", "description": "Inclusive end date for the chart window in `YYYY-MM-DD` format. Defaults to today.", "default": "2026-11-05" }, "required": false, "description": "Inclusive end date for the chart window in `YYYY-MM-DD` format. Defaults to today." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": [ "object", "null" ], "properties": { "data": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "rank": { "type": [ "integer", "null" ], "description": "Chart rank (lower is better; 1 = top of chart)." }, "added_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp of when this chart row was recorded." }, "code2": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-2 country code of the chart, or 'GLOBAL'." }, "plays": { "type": [ "integer", "null" ], "minimum": 0, "description": "Plays attributed to the track on the chart day." }, "duration": { "type": [ "string", "null" ], "description": "Chart cadence (e.g. 'daily', 'weekly')." }, "chart_type": { "type": [ "string", "null" ], "description": "Chart family within the platform (e.g. 'regional', 'viral', 'top')." }, "gnp": { "type": [ "string", "null" ], "description": "Genre/Niche/Period tag identifying the chart slice (platform-specific)." }, "pre_rank": { "type": [ "integer", "null" ], "description": "Rank on the previous chart period." }, "peak_rank": { "type": [ "integer", "null" ], "description": "Best (lowest-numbered) rank achieved across all observed days." }, "peak_date": { "type": [ "string", "null" ], "format": "date-time", "description": "Date when `peak_rank` was achieved." }, "peak_plays": { "type": [ "integer", "null" ], "minimum": 0, "description": "Plays recorded on `peak_date`." }, "total_plays": { "type": [ "integer", "null" ], "minimum": 0, "description": "Cumulative plays across all observed chart days." }, "id": { "type": "integer", "description": "Chartmetric track ID." }, "cm_track": { "type": "integer", "description": "Chartmetric track ID. Same value as `id`." }, "name": { "type": [ "string", "null" ], "description": "Track title." }, "isrc": { "type": [ "string", "null" ], "description": "International Standard Recording Code identifying the recording." }, "image_url": { "type": [ "string", "null" ], "description": "URL of the track artwork." }, "spotify_popularity": { "type": [ "integer", "null" ], "description": "Spotify popularity score (0–100, higher is more popular)." }, "spotify_duration_ms": { "type": [ "integer", "null" ], "description": "Track duration on Spotify in milliseconds." }, "cm_artist": { "type": [ "array", "null" ], "items": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "description": "Chartmetric artist IDs of the credited artists, ordered by main-artist-first." }, "artist_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Display names of the credited artists, aligned with `cm_artist`." }, "spotify_artist_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Spotify artist IDs of the credited artists." }, "spotify_artist_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Spotify display names of the credited artists." }, "spotify_track_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Spotify track IDs linked to this Chartmetric track." }, "spotify_album_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Spotify album IDs containing this track." }, "itunes_artist_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "iTunes/Apple Music artist IDs of the credited artists." }, "itunes_artist_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "iTunes/Apple Music display names of the credited artists." }, "itunes_track_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "iTunes/Apple Music track IDs linked to this Chartmetric track." }, "itunes_album_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "iTunes/Apple Music album IDs containing this track." }, "code2s": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "ISO 3166-1 alpha-2 country codes associated with the credited artists (e.g. 'US', 'BR')." }, "artist_images": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Profile image URLs of the credited artists." }, "artist_covers": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Cover/banner image URLs of the credited artists." }, "album_ids": { "type": [ "array", "null" ], "items": { "type": [ "integer", "null" ] }, "description": "Chartmetric album IDs that contain this track." }, "album_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Album titles aligned with `album_ids`." }, "album_upc": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Universal Product Codes for the albums in `album_ids`." }, "album_label": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Record labels for the albums in `album_ids`." }, "release_dates": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Release dates for the albums in `album_ids`, in `YYYY-MM-DD` or ISO-8601 form." }, "storefronts": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Apple Music storefront codes where the track was charted." }, "track_genre": { "anyOf": [ { "type": "string" }, { "type": "array", "items": {} } ], "nullable": true, "description": "Genre labels for the track. Either a comma-separated string or an array, depending on source." } } }, "description": "Chart rows for the track within the requested date window. Null when the track has no records on the chart." }, "length": { "type": "integer", "minimum": 0, "description": "Number of entries in `data`." } }, "required": [ "length" ] } }, "additionalProperties": false }, "examples": { "default": { "value": { "obj": { "data": [ { "rank": 104, "added_at": "2020-03-04T08:00:00.000Z", "code2": "GLOBAL", "plays": 1084704, "duration": "daily", "chart_type": "regional", "gnp": null, "pre_rank": 105, "peak_rank": 1, "peak_date": "2019-02-08T08:00:00.000Z", "peak_plays": 10445538, "total_plays": 1033605669, "name": "7 rings", "isrc": "USUM71900110", "image_url": "https://i.scdn.co/image/38205ab1bdc4b37b68b3ace40989afb6c2c1faa9", "spotify_popularity": 86, "cm_track": 22290726, "spotify_artist_names": [ "Ariana Grande" ], "track_genre": "dance pop,pop,post-teen pop", "cm_artist": [ 3963 ], "artist_names": [ "Ariana Grande" ], "code2s": [ "US" ], "artist_images": [ "https://i.scdn.co/image/b1dfbe843b0b9f54ab2e588f33e7637d2dab065a" ], "spotify_artist_ids": [ "66CXWjxzNUsdJxJ2JdwvnR" ], "spotify_track_ids": [ "6ocbgoVGwYJhOv1GgI9NsF" ], "spotify_album_ids": [ "2fYhqwDWXjbpjaIJPEfKFw" ], "spotify_duration_ms": 178626, "album_ids": [ 3532913 ], "album_names": [ "thank u, next" ], "album_upc": [ "602577490385" ], "album_label": [ "Republic Records" ], "release_dates": [ "2019-02-08T08:00:00.000Z" ] } ], "length": 33 } } } } } } } } } }, "/api/track/{type}/{id}/get-ids": { "get": { "summary": "Get Cross-Platform IDs for a Track", "tags": [ "Track" ], "operationId": "getTrackIds", "description": "Resolve cross-platform IDs from any single ID. `type` accepts `chartmetric`, `isrc`, `spotify`, `itunes`, `tiktok`, `genius`. All domain arrays may be `null` if the track has no linked ID in that domain.", "parameters": [ { "name": "type", "in": "path", "schema": { "type": "string", "enum": [ "amazon", "beatport", "chartmetric", "deezer", "genius", "isrc", "itunes", "shazam", "spotify", "soundcloud", "tiktok", "qq", "youtube" ], "description": "Domain of the input `id`. One of `chartmetric`, `isrc`, `spotify`, `itunes`, `tiktok`, `genius`, `amazon`, `beatport`, `deezer`, `qq`, `shazam`, `soundcloud`, `youtube`." }, "required": true, "description": "Domain of the input `id`. One of `chartmetric`, `isrc`, `spotify`, `itunes`, `tiktok`, `genius`, `amazon`, `beatport`, `deezer`, `qq`, `shazam`, `soundcloud`, `youtube`.", "examples": { "default": { "value": "amazon" } } }, { "name": "id", "in": "path", "schema": { "type": "string", "pattern": "^[a-zA-Z0-9-_]+$", "description": "ID for the domain specified by `type` (e.g. a Spotify track ID when `type=spotify`, an ISRC when `type=isrc`, a Chartmetric numeric ID when `type=chartmetric`)." }, "required": true, "description": "ID for the domain specified by `type` (e.g. a Spotify track ID when `type=spotify`, an ISRC when `type=isrc`, a Chartmetric numeric ID when `type=chartmetric`).", "examples": { "default": { "value": "2762" } } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "array", "items": { "type": "object", "properties": { "isrc": { "type": [ "string", "null" ], "description": "International Standard Recording Code identifying the recording." }, "chartmetric_ids": { "type": [ "array", "null" ], "items": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "description": "Chartmetric track IDs linked to this recording." }, "spotify_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Spotify track IDs linked to this recording, ordered by ingestion date then by latest popularity." }, "itunes_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "iTunes/Apple Music track IDs linked to this recording." }, "deezer_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Deezer track IDs linked to this recording." }, "amazon_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Amazon Music track IDs linked to this recording." }, "youtube_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "YouTube video IDs linked to this recording." }, "soundcloud_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "SoundCloud track IDs linked to this recording." }, "shazam_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Shazam track IDs linked to this recording." }, "tiktok_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "TikTok sound IDs linked to this recording." }, "beatport_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Beatport track IDs linked to this recording." }, "qq_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "QQ Music track IDs linked to this recording." }, "genius_ids": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Genius song IDs linked to this recording." } } } } }, "additionalProperties": false }, "examples": { "default": { "value": { "obj": [ { "isrc": "GBWHD0801085", "chartmetric_ids": [ 13106618 ], "spotify_ids": [ "35pIBRfhByXHvWkLBXIloT" ], "itunes_ids": [ "311034817" ], "deezer_ids": null, "amazon_ids": null, "youtube_ids": null, "soundcloud_ids": null, "shazam_ids": null, "tiktok_ids": [ "Smooth-Criminal-245073415512956928", "Smooth-Criminal-Instrumental-version-originally-performed-by-Michael-Jackson-6792293516425824257" ], "beatport_ids": null, "qq_ids": null, "genius_ids": null } ] } } } } } } } } }, "/api/track/{id}": { "get": { "summary": "Get Track Metadata by ID", "tags": [ "Track" ], "operationId": "getTrackById", "description": "Fetch a single Chartmetric track with full metadata: artists, albums, tags/genres, moods, activities, release info, and aggregated `cm_statistics` spanning Spotify, YouTube, TikTok, Shazam, Pandora, Genius, and Boomplay counters. Response may contain additional undocumented fields that can change over time.", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric track ID." }, "required": true, "description": "Chartmetric track ID.", "examples": { "default": { "value": 1 } } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "object", "properties": { "id": { "type": "integer", "description": "Chartmetric track ID." }, "name": { "type": [ "string", "null" ], "description": "Track title." }, "local_name": { "type": [ "string", "null" ], "description": "Localized track title, when available." }, "local_name_locale": { "type": [ "string", "null" ], "description": "Locale for local_name, when available." }, "isrc": { "type": [ "string", "null" ], "description": "International Standard Recording Code identifying the recording." }, "image_url": { "type": [ "string", "null" ], "description": "URL of the track artwork." }, "preview_url": { "type": [ "string", "null" ], "description": "URL of a short audio preview clip, if available." }, "duration_ms": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "nullable": true, "description": "Track duration in milliseconds. May arrive as numeric or string from ES." }, "composer_name": { "type": [ "string", "null" ], "description": "Track composer name (free-text, often `N/A`)." }, "track_tier": { "type": [ "integer", "null" ], "description": "Chartmetric track tier classification." }, "artists": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Chartmetric artist ID." }, "name": { "type": [ "string", "null" ], "description": "Artist display name." } }, "required": [ "id" ] }, "description": "Credited artists, ordered by main-artist-first. May include additional fields from the artist record." }, "albums": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Chartmetric album ID." }, "name": { "type": [ "string", "null" ], "description": "Album title." }, "upc": { "type": [ "string", "null" ], "description": "Universal Product Code identifying the release." }, "release_date": { "type": [ "string", "null" ], "format": "date-time", "description": "Album release date." }, "label": { "type": [ "string", "null" ], "description": "Record label that released the album." }, "image_url": { "type": [ "string", "null" ], "description": "URL of the album artwork." }, "popularity": { "type": [ "integer", "null" ], "description": "Album popularity score on the source platform." } } }, "description": "Albums that contain this track." }, "tags": { "type": [ "string", "null" ], "description": "Comma-separated genre/tag labels for the track." }, "moods": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ], "description": "Chartmetric mood ID." }, "name": { "type": [ "string", "null" ], "description": "Mood label." } } }, "description": "Mood tags applied to the track." }, "activities": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ], "description": "Chartmetric activity ID." }, "name": { "type": [ "string", "null" ], "description": "Activity label (e.g. workout, study)." } } }, "description": "Activity tags applied to the track." }, "genres": { "type": [ "array", "null" ], "items": {}, "description": "Genre objects applied to the track." }, "songwriters": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Songwriter names credited on the track." }, "cm_songwriters": { "type": [ "array", "null" ], "items": {}, "description": "Chartmetric songwriter records linked to the track." }, "release_date": { "type": [ "string", "null" ], "format": "date-time", "description": "Release date of the track's earliest album." }, "album_label": { "type": [ "string", "null" ], "description": "Label name of the track's earliest album." }, "explicit": { "type": [ "boolean", "null" ], "description": "True if the track is flagged as explicit." }, "score": { "type": [ "number", "null" ], "format": "float", "description": "Chartmetric track score (composite popularity metric)." }, "track_stage": { "description": "Internal track lifecycle stage classification." }, "career_health": { "description": "Internal track career-health classification." }, "cm_statistics": { "type": [ "object", "null" ], "properties": { "cm_track": { "type": [ "integer", "null" ], "description": "Chartmetric track ID (same as outer `id`)." }, "sp_popularity": { "type": [ "integer", "null" ], "description": "Spotify popularity score (0–100)." }, "num_sp_playlists": { "type": [ "integer", "null" ], "description": "Number of Spotify playlists featuring this track." }, "num_sp_editorial_playlists": { "type": [ "integer", "null" ], "description": "Number of Spotify editorial playlists featuring this track." }, "num_am_playlists": { "type": [ "integer", "null" ], "description": "Number of Apple Music playlists featuring this track." }, "num_am_editorial_playlists": { "type": [ "integer", "null" ], "description": "Number of Apple Music editorial playlists featuring this track." }, "num_de_playlists": { "type": [ "integer", "null" ], "description": "Number of Deezer playlists featuring this track." }, "num_de_editorial_playlists": { "type": [ "integer", "null" ], "description": "Number of Deezer editorial playlists featuring this track." }, "num_az_playlists": { "type": [ "integer", "null" ], "description": "Number of Amazon playlists featuring this track." }, "num_az_editorial_playlists": { "type": [ "integer", "null" ], "description": "Number of Amazon editorial playlists featuring this track." }, "num_yt_playlists": { "type": [ "integer", "null" ], "description": "Number of YouTube playlists featuring this track." }, "num_yt_editorial_playlists": { "type": [ "integer", "null" ], "description": "Number of YouTube editorial playlists featuring this track." }, "num_tt_videos": { "type": [ "integer", "null" ], "description": "TikTok video count using this track." }, "sp_playlist_total_reach": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Sum of followers across all Spotify playlists featuring the track. Surfaces as string from PG uncast aggregate." }, "sp_editorial_playlist_total_reach": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Sum of followers across Spotify editorial playlists featuring the track." }, "de_playlist_total_reach": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Sum of fans across all Deezer playlists featuring the track." }, "de_editorial_playlist_total_reach": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Sum of fans across Deezer editorial playlists featuring the track." }, "yt_playlist_total_reach": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Sum of views across all YouTube playlists featuring the track." }, "yt_editorial_playlist_total_reach": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Sum of views across YouTube editorial playlists featuring the track." }, "sp_streams": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Total Spotify stream count. May exceed int32 and arrive as string." }, "youtube_views": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Total YouTube view count. May exceed int32 and arrive as string." }, "soundcloud_playback_count": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Total SoundCloud playback count." }, "genius_page_views": { "type": [ "integer", "null" ], "description": "Genius lyrics page view count." }, "shazam_counts": { "type": [ "integer", "null" ], "description": "Total Shazam tag count." }, "tiktok_counts": { "type": [ "integer", "null" ], "description": "TikTok counter (legacy — alias of `num_tt_videos`)." }, "tiktok_trending_user": { "type": [ "string", "null" ], "description": "TikTok trending user ID for the track." }, "tiktok_trending_user_likes": { "type": [ "string", "null" ], "description": "TikTok trending user like count." }, "tiktok_trending_user_cm_artist": { "type": [ "integer", "null" ], "description": "Chartmetric artist ID of the TikTok trending user." }, "pandora_lifetime_streams": { "type": [ "integer", "null" ], "description": "Pandora lifetime stream count." }, "pandora_lifetime_stations_added": { "type": [ "integer", "null" ], "description": "Pandora lifetime stations-added count." }, "boomplay_comments": { "type": [ "string", "null" ], "description": "Boomplay comment count." }, "boomplay_favorites": { "type": [ "string", "null" ], "description": "Boomplay favorite count." }, "boomplay_shares": { "type": [ "string", "null" ], "description": "Boomplay share count." }, "line_music_likes": { "type": [ "string", "null" ], "description": "Line Music like count." }, "line_music_listen_count": { "type": [ "string", "null" ], "description": "Line Music listen count." }, "melon_likes": { "type": [ "string", "null" ], "description": "Melon like count." } }, "description": "Aggregated platform counters. Large counters (streams, views, playlist reach) surface as strings from uncast PG aggregates; small bounded counts stay numeric. Additional undocumented platform counters may appear as new sources are integrated." } }, "required": [ "id", "artists", "albums" ] } }, "required": [ "obj" ], "additionalProperties": false }, "examples": { "default": { "value": { "obj": { "id": 15678739, "name": "Angels", "local_name": null, "local_name_locale": null, "isrc": "USRC11700153", "image_url": "https://i.scdn.co/image/5026fddc6c0b69e931ae99130f15d4214f1e7d41", "preview_url": null, "duration_ms": 170680, "composer_name": "N/A", "track_tier": null, "artists": [ { "id": 209693, "name": "Khalid", "image_url": "https://i.scdn.co/image/ab6761610000e5eb012b37d6dec8872b18524f78", "code2": "US" } ], "albums": [ { "id": 13133047, "name": "American Teen", "upc": "886446326146", "release_date": "2017-03-03T08:00:00.000Z", "label": "Right Hand Music Group, LLC/RCA Records", "image_url": "https://is5-ssl.mzstatic.com/image/thumb/Music124/v4/5b/54/f9/5b54f992-e3b3-4809-fcc4-21a9faf484da/886446326146.jpg/160x160bb.jpeg", "popularity": null } ], "tags": "Music,R&B/Soul", "moods": null, "activities": null, "genres": null, "songwriters": null, "cm_songwriters": null, "release_date": "2017-03-03T00:00:00.000Z", "album_label": "Right Hand Music Group, LLC/RCA Records", "explicit": false, "score": null, "cm_statistics": { "cm_track": 15678739, "sp_popularity": 61, "num_tt_videos": 954, "sp_streams": "107823509", "genius_page_views": 297466, "youtube_views": "6800747" } } } } } } } } } } }, "/api/track/{id}/{platform}/playlists/snapshot": { "get": { "summary": "Get Track Playlist Snapshot by Date", "tags": [ "Track" ], "operationId": "getTrackPlaylistsSnapshot", "description": "Return the playlists a track belonged to on the given `date`. `platform` accepts `spotify`, `applemusic` (aliased to `itunes`), or `deezer`. Each entry pairs the playlist info with the track info at that snapshot.", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric track ID." }, "required": true, "description": "Chartmetric track ID.", "examples": { "default": { "value": 1 } } }, { "name": "platform", "in": "path", "schema": { "type": "string", "enum": [ "spotify", "applemusic", "itunes", "deezer" ], "description": "Streaming platform. One of `spotify`, `applemusic` (aliased to `itunes`), or `deezer`." }, "required": true, "description": "Streaming platform. One of `spotify`, `applemusic` (aliased to `itunes`), or `deezer`.", "examples": { "default": { "value": "spotify" } } }, { "name": "date", "in": "query", "schema": { "type": "string", "format": "date-time", "description": "Snapshot date in `YYYY-MM-DD` format. Returns playlists the track was on as of this date." }, "required": true, "description": "Snapshot date in `YYYY-MM-DD` format. Returns playlists the track was on as of this date.", "examples": { "default": { "value": "2024-01-01" } } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, "required": false, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum number of playlists to return. Max 100.", "default": 10 }, "required": false, "description": "Maximum number of playlists to return. Max 100." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "array", "items": { "type": "object", "properties": { "playlist_id": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Chartmetric playlist ID. May arrive as numeric or string." }, "track_id": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Internal track ID for the playlist-track pairing. Prefer `track.cm_track` for stable cross-reference." }, "added_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the track was added to the playlist." }, "removed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the track was removed from the playlist; null if still on it." }, "playlist": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "description": "Chartmetric playlist ID." }, "name": { "type": [ "string", "null" ], "description": "Playlist name." }, "playlist_id": { "type": [ "string", "null" ], "description": "Native playlist ID on the source platform (e.g. Spotify playlist URI suffix)." }, "description": { "type": [ "string", "null" ], "description": "Playlist description as set by the curator." }, "image_url": { "type": [ "string", "null" ], "description": "URL of the playlist cover artwork." }, "sys_last_updated": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp of the last Chartmetric stats refresh for this playlist." }, "last_updated": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp of the last upstream playlist update from the platform." }, "personalized": { "type": [ "boolean", "null" ], "description": "True if the playlist is personalized (e.g. Discover Weekly, Release Radar) and varies per listener." }, "code2": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-2 country code where the playlist is targeted (e.g. 'US')." }, "owner_name": { "type": [ "string", "null" ], "description": "Display name of the playlist curator/owner." }, "owner_id": { "type": [ "integer", "null" ], "description": "Chartmetric curator ID of the playlist owner." }, "user_id": { "type": [ "string", "null" ], "description": "Native user ID of the playlist owner on the source platform." }, "editorial": { "type": [ "boolean", "null" ], "description": "True if the playlist is curated by an official editorial team. Applies to Spotify, Apple Music, and Deezer." }, "tags": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Chartmetric tag ID." }, "name": { "type": "string", "description": "Tag name (e.g. genre or mood label)." } } }, "description": "Genre/mood tags applied to the playlist." }, "followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Current follower count of the playlist. May arrive as numeric or string." }, "num_track": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Number of tracks in the playlist. May arrive as numeric or string." }, "fdiff_week": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Week-over-week change in followers (`followers` minus the count seven days ago)." }, "fdiff_month": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Month-over-month change in followers (`followers` minus the count thirty days ago)." }, "catalog": { "type": [ "string", "null" ], "description": "Catalog classification for the playlist (e.g. `catalogue`, `current`)." }, "active_ratio": { "type": [ "number", "null" ], "format": "float", "description": "Fraction (0–1) of the playlist tracks that are recently active per Chartmetric heuristics." } }, "description": "Playlist metadata at the snapshot date." }, "track": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "description": "Chartmetric track ID." }, "cm_track": { "type": "integer", "description": "Chartmetric track ID. Same value as `id`." }, "name": { "type": [ "string", "null" ], "description": "Track title." }, "isrc": { "type": [ "string", "null" ], "description": "International Standard Recording Code identifying the recording." }, "image_url": { "type": [ "string", "null" ], "description": "URL of the track artwork." }, "spotify_popularity": { "type": [ "integer", "null" ], "description": "Spotify popularity score (0–100, higher is more popular)." }, "spotify_duration_ms": { "type": [ "integer", "null" ], "description": "Track duration on Spotify in milliseconds." }, "cm_artist": { "type": [ "array", "null" ], "items": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "description": "Chartmetric artist IDs of the credited artists, ordered by main-artist-first." }, "artist_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Display names of the credited artists, aligned with `cm_artist`." }, "spotify_artist_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Spotify artist IDs of the credited artists." }, "spotify_artist_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Spotify display names of the credited artists." }, "spotify_track_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Spotify track IDs linked to this Chartmetric track." }, "spotify_album_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Spotify album IDs containing this track." }, "itunes_artist_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "iTunes/Apple Music artist IDs of the credited artists." }, "itunes_artist_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "iTunes/Apple Music display names of the credited artists." }, "itunes_track_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "iTunes/Apple Music track IDs linked to this Chartmetric track." }, "itunes_album_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "iTunes/Apple Music album IDs containing this track." }, "code2s": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "ISO 3166-1 alpha-2 country codes associated with the credited artists (e.g. 'US', 'BR')." }, "artist_images": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Profile image URLs of the credited artists." }, "artist_covers": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Cover/banner image URLs of the credited artists." }, "album_ids": { "type": [ "array", "null" ], "items": { "type": [ "integer", "null" ] }, "description": "Chartmetric album IDs that contain this track." }, "album_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Album titles aligned with `album_ids`." }, "album_upc": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Universal Product Codes for the albums in `album_ids`." }, "album_label": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Record labels for the albums in `album_ids`." }, "release_dates": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Release dates for the albums in `album_ids`, in `YYYY-MM-DD` or ISO-8601 form." }, "storefronts": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Apple Music storefront codes where the track was charted." }, "track_genre": { "anyOf": [ { "type": "string" }, { "type": "array", "items": {} } ], "nullable": true, "description": "Genre labels for the track. Either a comma-separated string or an array, depending on source." } }, "description": "Track metadata at the snapshot date." } } } } }, "additionalProperties": false }, "examples": { "default": { "value": { "obj": [ { "playlist_id": 688460, "track_id": 9874724, "added_at": "2018-09-27T00:00:00.000Z", "removed_at": "2020-02-09T08:11:39.008Z", "playlist": { "id": 688460, "name": "NEW POP HITS 2014-HEUTE", "playlist_id": "6JjPdcrvR4l6ZAoga2EFqh", "description": "NEW POP HITS 2014-HEUTE (Daily Updated Music) by DjCK", "image_url": "https://i.scdn.co/image/ab67706c0000bebb198fdd7caeedd2d8517f35c7", "sys_last_updated": "2020-12-21T20:40:25.686Z", "last_updated": "2020-12-21T20:40:17.114Z", "personalized": false, "code2": null, "owner_name": "Christian Kreitz", "owner_id": 11781, "user_id": "1156916120", "editorial": false, "tags": [ { "id": 188, "name": "pop" }, { "id": 8893, "name": "dance pop" } ], "followers": 3, "num_track": "3056", "fdiff_week": 0, "fdiff_month": 0, "catalog": "catalogue ", "active_ratio": 0.032068 }, "track": { "id": 9874724, "name": "Taki Taki (with Selena Gomez, Ozuna & Cardi B)", "isrc": "USUG11801723", "image_url": "https://i.scdn.co/image/cca02c139eb4270d5e396086329c97c782c7b478", "spotify_popularity": 80, "cm_track": 20614006, "spotify_artist_names": [ "DJ Snake", "Selena Gomez" ], "track_genre": "dance pop,pop", "cm_artist": [ 4310, 3168 ], "artist_names": [ "DJ Snake", "Selena Gomez" ], "code2s": [ "FR", "US" ], "artist_images": [ "https://i.scdn.co/image/3b232935a2d2dc1fcc3bfd8db2d6be58292b2317", "https://i.scdn.co/image/61fc36467d4945514cdf052ed49286aa8ea3b4fc" ], "artist_covers": [ null, null ], "spotify_artist_ids": [ "540vIaP2JwjQb9dm3aArA4", "0C8ZW7ezQVs4URX5aX7Kqx" ], "spotify_track_ids": [ "4w8niZpiMy6qz1mntFA5uM" ], "spotify_album_ids": [ "0ZHyvPke0EcVt6rYA8Ins3" ], "spotify_duration_ms": 212500, "album_ids": [ 2812303 ], "album_names": [ "Taki Taki (with Selena Gomez, Ozuna & Cardi B)" ], "album_upc": [ "602577004803" ], "album_label": [ "DJ Snake Music Productions Limited, under exclusive license to Geffen Records" ], "release_dates": [ "2018-09-28T00:00:00.000Z" ] } } ] } } } } } } } } }, "/api/track/{id}/{platform}/stats/{mode}": { "get": { "summary": "Get Track Stats by Platform", "tags": [ "Track" ], "operationId": "getTrackStats", "description": "Return historical stats for a track on a platform. `mode` selects the aggregation bucket. `platform` accepts `chartmetric`, `spotify`, `youtube`, `tiktok`, etc. `type` query param selects the stat column (e.g. `streams`, `popularity`). Wrapped in a single-element array under `obj`.", "parameters": [ { "name": "platform", "in": "path", "schema": { "type": "string", "enum": [ "shazam", "spotify", "youtube", "tiktok", "genius", "soundcloud", "chartmetric", "line", "melon", "radio" ], "description": "Streaming platform whose stats to retrieve. One of `shazam`, `spotify`, `youtube`, `tiktok`, `genius`, `soundcloud`, `chartmetric`, `line`, `melon`, `radio`." }, "required": true, "description": "Streaming platform whose stats to retrieve. One of `shazam`, `spotify`, `youtube`, `tiktok`, `genius`, `soundcloud`, `chartmetric`, `line`, `melon`, `radio`.", "examples": { "default": { "value": "shazam" } } }, { "name": "id", "in": "path", "schema": { "anyOf": [ { "anyOf": [ { "type": "integer", "x-required": true }, { "type": "string", "x-required": true } ] }, { "type": "integer", "minimum": 1, "x-required": true } ], "description": "Track identifier. By default a Chartmetric track ID; if `isDomainId=true`, a platform-native ID (numeric for `shazam`/`genius`, string for others)." }, "required": true, "description": "Track identifier. By default a Chartmetric track ID; if `isDomainId=true`, a platform-native ID (numeric for `shazam`/`genius`, string for others).", "examples": { "default": { "value": 1 } } }, { "name": "mode", "in": "path", "schema": { "type": "string", "enum": [ "highest-playcounts", "most-history" ], "description": "Selection algorithm when multiple platform tracks map to one Chartmetric track. `highest-playcounts` picks the most-played; `most-history` picks the longest-tracked." }, "required": true, "description": "Selection algorithm when multiple platform tracks map to one Chartmetric track. `highest-playcounts` picks the most-played; `most-history` picks the longest-tracked.", "examples": { "default": { "value": "highest-playcounts" } } }, { "name": "since", "in": "query", "schema": { "type": "string", "format": "date", "description": "Inclusive start of the stat date range in `YYYY-MM-DD` format. Defaults to 180 days before today.", "default": "2026-05-09" }, "required": false, "description": "Inclusive start of the stat date range in `YYYY-MM-DD` format. Defaults to 180 days before today." }, { "name": "type", "in": "query", "schema": { "anyOf": [ { "type": "string", "enum": [ "total_spins" ], "default": "total_spin" }, { "type": "string", "enum": [ "listen_count", "artist_likes" ], "default": "listen_count" }, { "type": "string", "enum": [ "likes_melon" ], "default": "likes_melon" }, { "type": "string", "enum": [ "streams", "popularity" ], "default": "popularity" }, { "type": "string", "enum": [ "score", "rank" ], "default": "score" }, { "type": "string", "enum": [ "posts", "views", "comments", "sound_posts", "sound_views", "sound_likes", "sound_comments" ], "default": "posts" }, { "type": "string" } ], "description": "Stat column to retrieve; allowed values depend on `platform` (e.g. spotify → `streams`/`popularity`; tiktok → `posts`/`views`/`sound_*`). Each platform has a default." }, "required": false, "description": "Stat column to retrieve; allowed values depend on `platform` (e.g. spotify → `streams`/`popularity`; tiktok → `posts`/`views`/`sound_*`). Each platform has a default." }, { "name": "until", "in": "query", "schema": { "type": "string", "format": "date", "description": "Inclusive end of the stat date range in `YYYY-MM-DD` format. Defaults to today.", "default": "2026-11-05" }, "required": false, "description": "Inclusive end of the stat date range in `YYYY-MM-DD` format. Defaults to today." }, { "name": "latest", "in": "query", "schema": { "type": "boolean", "description": "If true, return only the most recent data point regardless of `since`/`until`." }, "required": false, "description": "If true, return only the most recent data point regardless of `since`/`until`." }, { "name": "interpolated", "in": "query", "schema": { "type": "boolean", "description": "If true, fill gaps in the time series with interpolated values to produce a smooth curve. Not applicable for Spotify." }, "required": false, "description": "If true, fill gaps in the time series with interpolated values to produce a smooth curve. Not applicable for Spotify." }, { "name": "isDomainId", "in": "query", "schema": { "type": "boolean", "description": "If true, treat `id` as a platform-native ID rather than a Chartmetric track ID. Defaults to false.", "default": false }, "required": false, "description": "If true, treat `id` as a platform-native ID rather than a Chartmetric track ID. Defaults to false." }, { "name": "extrapolated", "in": "query", "schema": { "type": "string", "enum": [ "before", "after", "both" ], "description": "Extrapolation mode for projecting values outside the observed range. One of `before`, `after`, `both`." }, "required": false, "description": "Extrapolation mode for projecting values outside the observed range. One of `before`, `after`, `both`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string", "description": "Streaming platform that produced the stats (e.g. 'spotify', 'youtube')." }, "track_domain_id": { "type": [ "string", "null" ], "description": "Native track ID on `domain`." }, "type": { "type": [ "string", "null" ], "description": "Stat column returned (e.g. 'streams', 'popularity', 'posts')." }, "data": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Stat value at the timestamp. May arrive as numeric or string for large counters." }, "timestp": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp of the data point in ISO-8601 form." }, "daily_diff": { "type": [ "number", "null" ], "format": "float", "description": "Day-over-day change in `value`. Not applicable for Spotify." }, "interpolated": { "type": "boolean", "description": "True if `value` was interpolated to fill a gap rather than observed directly. Not applicable for Spotify." } } }, "description": "Time series of stat values for the track on the platform." } }, "required": [ "domain" ] }, "minItems": 1, "maxItems": 1 } }, "additionalProperties": false }, "examples": { "default": { "value": { "obj": [ { "domain": "spotify", "track_domain_id": "55n9yjI6qqXh5F2mYvUc2y", "type": "streams", "data": [ { "value": 80, "timestp": "2022-01-01T00:00:00.000Z" }, { "value": 80, "timestp": "2022-01-02T00:00:00.000Z" } ] } ] } } } } } } } } }, "/api/track/youtube/{id}/topShorts": { "get": { "summary": "List Top YouTube Shorts for a Track", "tags": [ "Track" ], "operationId": "listTrackTopYouTubeShorts", "description": "Return the top YouTube Shorts videos associated with a track. View/like/comment counts may exceed int32.", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric track ID." }, "required": true, "description": "Chartmetric track ID.", "examples": { "default": { "value": 1 } } }, { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "likes", "views", "comments", "trending", "created_at" ], "description": "Sort metric for the returned Shorts. Defaults to `likes`; allowed values come from YouTube engagement stats.", "default": "likes" }, "required": false, "description": "Sort metric for the returned Shorts. Defaults to `likes`; allowed values come from YouTube engagement stats." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum number of Shorts to return. Max 100.", "default": 10 }, "required": false, "description": "Maximum number of Shorts to return. Max 100." }, { "name": "bySoundId", "in": "query", "schema": { "type": "boolean", "description": "If true, treat `id` as a YouTube sound ID rather than a Chartmetric track ID. Defaults to false.", "default": false }, "required": false, "description": "If true, treat `id` as a YouTube sound ID rather than a Chartmetric track ID. Defaults to false." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": [ "object", "null" ], "properties": { "total": { "type": [ "integer", "null" ], "minimum": 0, "description": "Total number of YouTube Shorts associated with the track across all sources." }, "available_count": { "type": [ "integer", "null" ], "description": "Count of Shorts available in `data` after filtering." }, "data": { "type": "array", "items": { "type": "object", "properties": { "video_id": { "type": [ "string", "null" ], "description": "YouTube Shorts video ID." }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Date the video was uploaded (ISO-8601)." }, "modified_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Date the video metadata was last refreshed (ISO-8601)." }, "username": { "type": [ "string", "null" ], "description": "YouTube channel handle of the uploader (with '@' prefix)." }, "video_title": { "type": [ "string", "null" ], "description": "Video title." }, "cm_id": { "type": [ "integer", "null" ], "description": "Chartmetric artist ID of the uploader, when linked." }, "sound_id": { "type": [ "string", "null" ], "description": "YouTube Shorts sound ID associated with the video." }, "token_parameter": { "type": [ "string", "null" ], "description": "Opaque token used by YouTube for navigation/lookups." }, "thumbnail_url": { "type": [ "string", "null" ], "description": "URL of the video thumbnail." }, "link": { "type": [ "string", "null" ], "description": "Direct URL to the YouTube Shorts video." }, "shorts_track_page": { "type": [ "string", "null" ], "description": "URL of the YouTube Shorts page aggregating videos using this sound." }, "views": { "type": [ "integer", "null" ], "minimum": 0, "description": "Cumulative view count for the video." }, "likes": { "type": [ "integer", "null" ], "minimum": 0, "description": "Cumulative like count for the video." }, "comments": { "type": [ "integer", "null" ], "minimum": 0, "description": "Cumulative comment count for the video." }, "stats": { "type": [ "object", "null" ], "properties": { "views": { "type": [ "integer", "null" ], "minimum": 0, "description": "Cumulative view count for the video." }, "likes": { "type": [ "integer", "null" ], "minimum": 0, "description": "Cumulative like count for the video." }, "comments": { "type": [ "integer", "null" ], "minimum": 0, "description": "Cumulative comment count for the video." } }, "description": "Engagement stats for the video." }, "influencercountries": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Country codes of audience countries where the uploader has influence (may be empty)." }, "youtubevideohistoricalstats": { "type": [ "array", "null" ], "items": {}, "description": "Historical view/like/comment data points for the video (may be empty)." }, "metadata_for_url": { "type": [ "object", "null" ], "properties": { "video_id": { "type": [ "string", "null" ], "description": "YouTube Shorts video ID." }, "username": { "type": [ "string", "null" ], "description": "Video creator username." }, "views": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "View count." }, "likes": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Like count." }, "comments": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Comment count." }, "created_at": { "type": [ "string", "null" ], "description": "Video creation date (YYYY-MM-DD)." } }, "description": "Compact metadata bundle suitable for link previews." } } }, "description": "Top YouTube Shorts using the track, sorted by the requested metric." } }, "required": [ "data" ] } }, "additionalProperties": false }, "examples": { "default": { "value": { "obj": { "total": 6400000, "available_count": 10, "data": [ { "video_id": "5VhmJaKV10c", "created_at": "2025-03-04T11:22:15.890Z", "modified_at": "2025-07-15T09:19:53.132Z", "username": "@roses_are_rosie", "video_title": "excited to see what shorts ideas y’all come up with for apt.💗 brought to you by youtube shorts", "cm_id": 138071658, "sound_id": "DiTd771WumE", "token_parameter": "8gVNCkASMQoLRGlUZDc3MVd1bUUSC0RpVGQ3NzFXdW1FGgtvYzN1WXRQYXd3dw==", "thumbnail_url": "https://i.ytimg.com/vi/5VhmJaKV10c/maxresdefault.jpg", "link": "https://www.youtube.com/shorts/5VhmJaKV10c", "shorts_track_page": "https://www.youtube.com/source/DiTd771WumE/shorts?app=desktop", "views": 247428457, "likes": 7235195, "comments": 70705, "stats": { "views": 247428457, "likes": 7235195, "comments": 70705 }, "influencercountries": [], "youtubevideohistoricalstats": [], "metadata_for_url": { "video_id": "5VhmJaKV10c", "username": "@roses_are_rosie", "views": 247428457, "likes": 7235195, "comments": 70705, "created_at": "2025-07-15" } } ] } } } } } } } } } }, "/api/track/{id}/tiktok-top-influencers": { "get": { "summary": "💎 Premium — List Top TikTok Influencers for a Track", "tags": [ "Track" ], "operationId": "listTrackTikTokTopInfluencers", "description": "The TikTok creators who used the track's sound, one row each -- the table the app shows on its TikTok page. Where the breakdown endpoint reports how the group splits by country or language, this reports who the creators are. Paged and filterable on every column the app's own filters use; `total` counts what matches the current filters rather than the whole set.", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric track ID." }, "required": true, "description": "Chartmetric track ID.", "examples": { "default": { "value": 1 } } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Influencers per page. Defaults to 25, max 100.", "default": 25 }, "required": false, "description": "Influencers per page. Defaults to 25, max 100." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Influencers to skip, for paging past the first `limit` rows. Defaults to 0, max 10,000." }, "required": false, "description": "Influencers to skip, for paging past the first `limit` rows. Defaults to 0, max 10,000." }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "enum": [ "rank", "totalFollowers", "totalViews", "totalLikes", "totalComments", "engagementRate", "totalSaves", "totalShares", "dateAdded", "avgViews", "avgLikes", "avgComments", "avgSaves", "avgShares", "avgEngagementRate", "videoCount", "lastDatePosted" ], "description": "Column to sort by. Defaults to `rank`, the order the app lists them in.", "default": "rank" }, "required": false, "description": "Column to sort by. Defaults to `rank`, the order the app lists them in." }, { "name": "sortDirection", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort direction. Defaults to `asc`.", "default": "asc" }, "required": false, "description": "Sort direction. Defaults to `asc`." }, { "name": "isVerified", "in": "query", "schema": { "type": "boolean", "description": "Restrict to verified accounts when true, unverified when false. Omit for both." }, "required": false, "description": "Restrict to verified accounts when true, unverified when false. Omit for both." }, { "name": "country[]", "in": "query", "schema": { "type": "array", "items": { "type": "string" }, "description": "ISO 3166-1 alpha-2 country codes to include. Repeat the param or pass a comma-free list." }, "required": false, "description": "ISO 3166-1 alpha-2 country codes to include. Repeat the param or pass a comma-free list." }, { "name": "categories[]", "in": "query", "schema": { "type": "array", "items": { "type": "string" }, "description": "Broad content categories to include. Repeat the param or pass a comma-free list." }, "required": false, "description": "Broad content categories to include. Repeat the param or pass a comma-free list." }, { "name": "ageGroup[]", "in": "query", "schema": { "type": "array", "items": { "type": "string" }, "description": "Age brackets, e.g. `18-24` to include. Repeat the param or pass a comma-free list." }, "required": false, "description": "Age brackets, e.g. `18-24` to include. Repeat the param or pass a comma-free list." }, { "name": "gender[]", "in": "query", "schema": { "type": "array", "items": { "type": "string" }, "description": "Genders to include. Repeat the param or pass a comma-free list." }, "required": false, "description": "Genders to include. Repeat the param or pass a comma-free list." }, { "name": "ethnicity[]", "in": "query", "schema": { "type": "array", "items": { "type": "string" }, "description": "Ethnicities to include. Repeat the param or pass a comma-free list." }, "required": false, "description": "Ethnicities to include. Repeat the param or pass a comma-free list." }, { "name": "language[]", "in": "query", "schema": { "type": "array", "items": { "type": "string" }, "description": "Primary languages to include. Repeat the param or pass a comma-free list." }, "required": false, "description": "Primary languages to include. Repeat the param or pass a comma-free list." }, { "name": "type[]", "in": "query", "schema": { "type": "array", "items": { "type": "string" }, "description": "Creator types, e.g. `Brand` to include. Repeat the param or pass a comma-free list." }, "required": false, "description": "Creator types, e.g. `Brand` to include. Repeat the param or pass a comma-free list." }, { "name": "minFollowers", "in": "query", "schema": { "type": "number", "format": "float", "description": "Only influencers with at least this followers." }, "required": false, "description": "Only influencers with at least this followers." }, { "name": "maxFollowers", "in": "query", "schema": { "type": "number", "format": "float", "description": "Only influencers with at most this followers." }, "required": false, "description": "Only influencers with at most this followers." }, { "name": "minAvgViews", "in": "query", "schema": { "type": "number", "format": "float", "description": "Only influencers with at least this average views." }, "required": false, "description": "Only influencers with at least this average views." }, { "name": "maxAvgViews", "in": "query", "schema": { "type": "number", "format": "float", "description": "Only influencers with at most this average views." }, "required": false, "description": "Only influencers with at most this average views." }, { "name": "minAvgLikes", "in": "query", "schema": { "type": "number", "format": "float", "description": "Only influencers with at least this average likes." }, "required": false, "description": "Only influencers with at least this average likes." }, { "name": "maxAvgLikes", "in": "query", "schema": { "type": "number", "format": "float", "description": "Only influencers with at most this average likes." }, "required": false, "description": "Only influencers with at most this average likes." }, { "name": "minAvgComments", "in": "query", "schema": { "type": "number", "format": "float", "description": "Only influencers with at least this average comments." }, "required": false, "description": "Only influencers with at least this average comments." }, { "name": "maxAvgComments", "in": "query", "schema": { "type": "number", "format": "float", "description": "Only influencers with at most this average comments." }, "required": false, "description": "Only influencers with at most this average comments." }, { "name": "minAvgSaves", "in": "query", "schema": { "type": "number", "format": "float", "description": "Only influencers with at least this average saves." }, "required": false, "description": "Only influencers with at least this average saves." }, { "name": "maxAvgSaves", "in": "query", "schema": { "type": "number", "format": "float", "description": "Only influencers with at most this average saves." }, "required": false, "description": "Only influencers with at most this average saves." }, { "name": "minAvgShares", "in": "query", "schema": { "type": "number", "format": "float", "description": "Only influencers with at least this average shares." }, "required": false, "description": "Only influencers with at least this average shares." }, { "name": "maxAvgShares", "in": "query", "schema": { "type": "number", "format": "float", "description": "Only influencers with at most this average shares." }, "required": false, "description": "Only influencers with at most this average shares." }, { "name": "minAvgEngagementRate", "in": "query", "schema": { "type": "number", "format": "float", "description": "Only influencers with at least this average engagement rate." }, "required": false, "description": "Only influencers with at least this average engagement rate." }, { "name": "maxAvgEngagementRate", "in": "query", "schema": { "type": "number", "format": "float", "description": "Only influencers with at most this average engagement rate." }, "required": false, "description": "Only influencers with at most this average engagement rate." }, { "name": "minVideoCount", "in": "query", "schema": { "type": "number", "format": "float", "description": "Only influencers with at least this video count." }, "required": false, "description": "Only influencers with at least this video count." }, { "name": "maxVideoCount", "in": "query", "schema": { "type": "number", "format": "float", "description": "Only influencers with at most this video count." }, "required": false, "description": "Only influencers with at most this video count." }, { "name": "lastDatePostedFrom", "in": "query", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Only influencers who last posted on or after this date (`YYYY-MM-DD`)." }, "required": false, "description": "Only influencers who last posted on or after this date (`YYYY-MM-DD`)." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "full_name": { "type": [ "string", "null" ], "description": "The creator's display name." }, "handle": { "type": [ "string", "null" ], "description": "TikTok handle, including the leading `@`." }, "is_verified": { "type": "boolean", "description": "Whether TikTok verifies the account." }, "country": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-2 code for the creator's own country." }, "contacts": { "type": "array", "items": { "type": "string" }, "description": "Public contact links the creator lists." }, "type": { "type": [ "string", "null" ], "description": "Creator classification, e.g. `Brand`, `Celebrity`, `Social Media Creator`." }, "language": { "type": [ "string", "null" ], "description": "The creator's primary language, lower-case." }, "ethnicity": { "type": "array", "items": { "type": "string" }, "description": "Ethnicities attributed to the creator, lower-case." }, "age_group": { "type": [ "string", "null" ], "description": "Age bracket, e.g. `18-24`." }, "gender": { "type": [ "string", "null" ], "description": "Gender, lower-case." }, "categories": { "type": "array", "items": { "type": "string" }, "description": "Broad content categories." }, "sub_categories": { "type": "array", "items": { "type": "string" }, "description": "Granular creator tags underneath those categories." }, "top_hashtags": { "type": "array", "items": { "type": "string" }, "description": "Hashtags the creator uses most." }, "genres": { "type": "array", "items": { "type": "string" }, "description": "Music genres attributed to the creator." }, "bio": { "type": [ "string", "null" ], "description": "The creator's TikTok bio." }, "featured_track": { "type": [ "string", "null" ], "description": "Name of the track their video used." }, "followers": { "type": [ "integer", "null" ], "description": "TikTok follower count." }, "engagement_rate": { "type": [ "number", "null" ], "format": "float", "description": "Engagement rate averaged across the creator's recent videos." }, "avg_views": { "type": [ "integer", "null" ], "description": "Views averaged across those videos." }, "avg_likes": { "type": [ "integer", "null" ], "description": "Likes averaged across those videos." }, "avg_comments": { "type": [ "integer", "null" ], "description": "Comments averaged across those videos." }, "avg_saves": { "type": [ "integer", "null" ], "description": "Saves averaged across those videos." }, "avg_shares": { "type": [ "integer", "null" ], "description": "Shares averaged across those videos." }, "video_count": { "type": [ "integer", "null" ], "description": "Videos on the account." }, "top_videos": { "type": "array", "items": { "type": "object", "properties": { "video_id": { "type": [ "string", "null" ], "description": "TikTok's ID for the video." }, "video_url": { "type": [ "string", "null" ], "description": "Direct link to the video." }, "thumbnail_url": { "type": [ "string", "null" ], "description": "Thumbnail URL." }, "views": { "type": [ "integer", "null" ], "description": "Views on the video." }, "likes": { "type": [ "integer", "null" ], "description": "Likes on the video." }, "comments": { "type": [ "integer", "null" ], "description": "Comments on the video." }, "saves": { "type": [ "integer", "null" ], "description": "Saves on the video." }, "shares": { "type": [ "integer", "null" ], "description": "Shares on the video." }, "engagement_rate": { "type": [ "number", "null" ], "format": "float", "description": "Engagement rate for the video." }, "created_at": { "type": [ "string", "null" ], "description": "Date the video was posted." }, "description": { "type": [ "string", "null" ], "description": "The video's caption." }, "track_name": { "type": [ "string", "null" ], "description": "Track the video's sound belongs to." } } }, "description": "Up to five of the creator's videos using the queried sounds." } } }, "description": "Influencers on this page." }, "total": { "type": "integer", "minimum": 0, "description": "Influencers matching the current filters, across all pages." } }, "required": [ "data", "total" ] } }, "additionalProperties": false }, "examples": { "default": { "value": { "obj": { "total": 384, "data": [ { "full_name": "Hailey Bieber", "handle": "@haileybieber", "is_verified": true, "country": "US", "contacts": [], "type": "Celebrity", "language": "english", "ethnicity": [ "white" ], "age_group": "25-34", "gender": "female", "categories": [ "Beauty & Cosmetics" ], "sub_categories": [ "makeup", "skincare" ], "top_hashtags": [ "rhodeskin", "grwm" ], "genres": [ "pop" ], "bio": "founder of rhode", "featured_track": "Choosin' Texas", "followers": 19338972, "engagement_rate": 0.0077, "avg_views": 418531, "avg_likes": 42600, "avg_comments": 253, "avg_saves": 2024, "avg_shares": 1875, "video_count": 8233, "top_videos": [ { "video_id": "7638754937748360478", "video_url": "https://www.tiktok.com/@haileybieber/video/7638754937748360478", "thumbnail_url": "https://d2xuw6r9djpzwq.cloudfront.net/tiktok/videos/7638754937748360478.jpg", "views": 27629256, "likes": 3056560, "comments": 13728, "saves": 138553, "shares": 74701, "engagement_rate": 0.1161, "created_at": "2026-05-11", "description": "Choosin' Texas", "track_name": "Choosin' Texas" } ] } ] } } } } } } } } } }, "/api/track/{id}/tiktok-influencer-stats": { "get": { "summary": "💎 Premium — Get Influencer Breakdown for a Track", "tags": [ "Track" ], "operationId": "getTrackTikTokInfluencerStats", "description": "Distribution of the TikTok creators who used the track's sounds, one axis per call. `dimension` selects the axis: `country`, `category` (broad content categories), `subcategory` (the granular creator tags beneath them), `age-gender`, or `language`. Aggregates only — the endpoint reports how many creators fall in each bucket, not who they are. A creator holds exactly one country, age/gender bucket and language, so those shares sum to 1 and `total` is the creator count; a creator can hold several categories, so `category` and `subcategory` return counts with `share` and `total` null and `multi_label` true.", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric track ID." }, "required": true, "description": "Chartmetric track ID.", "examples": { "default": { "value": 1 } } }, { "name": "dimension", "in": "query", "schema": { "type": "string", "enum": [ "country", "category", "subcategory", "age-gender", "language" ], "description": "Which breakdown to return. `category` is the broad creator-content layer, `subcategory` the granular one; a creator can hold several of either, so those two report counts without a share.", "default": "country" }, "required": false, "description": "Which breakdown to return. `category` is the broad creator-content layer, `subcategory` the granular one; a creator can hold several of either, so those two report counts without a share." }, { "name": "periodDays", "in": "query", "schema": { "type": "number", "format": "float", "enum": [ 0, 7, 30, 90 ], "description": "Rolling window, in days, over the date creators last posted with the track's sounds. `0` covers all time." }, "required": false, "description": "Rolling window, in days, over the date creators last posted with the track's sounds. `0` covers all time." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "object", "properties": { "dimension": { "type": "string", "enum": [ "country", "category", "subcategory", "age-gender", "language" ], "description": "The requested dimension, echoed back." }, "period_days": { "type": "number", "format": "float", "enum": [ 0, 7, 30, 90 ], "description": "The requested rolling window in days, echoed back. `0` covers all time." }, "total": { "type": [ "integer", "null" ], "minimum": 0, "description": "Creators the distribution covers. Null on the multi-label dimensions, where counts cannot be summed into a creator total." }, "multi_label": { "type": "boolean", "description": "True when a creator can appear in more than one bucket — `category` and `subcategory`. Those dimensions report counts without a share." }, "available_period_days": { "type": [ "array", "null" ], "items": { "type": "number", "format": "float" }, "description": "Windows this data is held for. Populated for `age-gender` and `language`; null elsewhere." }, "data": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "description": "Bucket label — an ISO 3166-1 alpha-2 code for `country`, `age|gender` for `age-gender`, otherwise the category, tag or language name." }, "count": { "type": "integer", "minimum": 0, "description": "Creators in this bucket." }, "share": { "type": [ "number", "null" ], "format": "float", "description": "Bucket's fraction of `total`, 0–1. Null on the multi-label dimensions." }, "delta": { "type": [ "integer", "null" ], "description": "Change in `count` against the preceding window of the same length. Null where the dimension carries no comparison." }, "age_group": { "type": [ "string", "null" ], "description": "Age bracket half of `value`. Present on `age-gender` only; null when the classifier resolved a gender but no age." }, "gender": { "type": [ "string", "null" ], "description": "Gender half of `value`. Present on `age-gender` only; null when the classifier resolved an age but no gender." } }, "required": [ "value", "count" ] }, "description": "Buckets, largest first." } }, "required": [ "dimension", "period_days", "multi_label", "data" ] } }, "additionalProperties": false }, "examples": { "default": { "value": { "obj": { "dimension": "age-gender", "period_days": 30, "total": 91, "multi_label": false, "available_period_days": [ 0, 7, 30, 90 ], "data": [ { "value": "25-34|female", "age_group": "25-34", "gender": "female", "count": 31, "share": 0.340659, "delta": 6 }, { "value": "18-24|female", "age_group": "18-24", "gender": "female", "count": 30, "share": 0.32967, "delta": -6 } ] } } } } } } } } } }, "/api/track/{id}/tiktok-top-sounds": { "get": { "summary": "💎 Premium — List Popular TikTok Sounds for a Track", "tags": [ "Track" ], "operationId": "listTrackTikTokTopSounds", "description": "The TikTok sounds carrying the track's audio that have been active recently, one row each -- the Top Sounds table on the track's TikTok page. A track usually has many: one official sound plus the user uploads that spread separately, each with its own video count and reach. This is not every sound we hold: a sound is returned when we have video stats for it inside the seven-day trend window and it is not a de-duplicated entry, so dormant sounds drop out -- on the track behind the example our cache holds 436 and 134 come back, the same set the app's own table renders. Rows come back ordered by views, highest first, and `video_trend` carries a daily video count reaching seven days back so a caller can tell a sound that is still spreading from one that has stalled.", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric track ID." }, "required": true, "description": "Chartmetric track ID.", "examples": { "default": { "value": 1 } } }, { "name": "official", "in": "query", "schema": { "type": "boolean", "description": "Restrict to sounds TikTok marks official when true, to the rest when false. Omit for both." }, "required": false, "description": "Restrict to sounds TikTok marks official when true, to the rest when false. Omit for both." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "array", "items": { "type": "object", "properties": { "tiktok": { "type": [ "integer", "null" ], "description": "Chartmetric's own ID for the sound." }, "tiktok_track_id": { "type": [ "string", "null" ], "description": "TikTok's ID for the sound, as Chartmetric stores it. Many carry an `x-` prefix -- on the track behind the example, all 134 did, official and not alike -- so the prefix is not a marker for anything a caller should branch on." }, "name": { "type": [ "string", "null" ], "description": "Sound title as it appears on TikTok." }, "creator_name": { "type": [ "string", "null" ], "description": "Who TikTok credits the sound to." }, "views": { "type": [ "integer", "null" ], "description": "Views across every video using the sound." }, "posts": { "type": [ "integer", "null" ], "description": "Videos using the sound." }, "first_post_date": { "type": [ "string", "null" ], "description": "Date the earliest video using the sound was posted, `YYYY-MM-DD`. Null for sounds with no videos in our video history yet." }, "upload_date": { "type": [ "string", "null" ], "description": "Date the sound went up on TikTok, `YYYY-MM-DD`." }, "is_official": { "type": "boolean", "description": "Whether the sound is flagged as the track's official sound. Typically one sound per track carries this and the rest are user uploads of the same audio -- 1 of 134 on the track behind the example." }, "is_original": { "type": "boolean", "description": "Whether TikTok marks the sound as original audio." }, "is_ai_generated": { "type": "boolean", "description": "Whether TikTok flags the sound as AI-generated." }, "still_on_tiktok": { "type": "boolean", "description": "Whether the sound is still live on TikTok." }, "thumbnail_url": { "type": [ "string", "null" ], "description": "Sound artwork." }, "video_trend": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": [ "string", "null" ], "description": "Date of the reading, `YYYY-MM-DD`." }, "videos": { "type": [ "integer", "null" ], "description": "Videos using the sound on that date." } } }, "description": "Daily count of videos using the sound, oldest first. The window reaches seven days back, so up to eight dated readings come back. Sounds with no new videos across the window report an empty array." } } } } }, "additionalProperties": false }, "examples": { "default": { "value": { "obj": [ { "tiktok": 25646255, "tiktok_track_id": "x-7559312683885201425", "name": "Choosin' Texas", "creator_name": "Ella Langley", "views": 989416726, "posts": 356929, "first_post_date": null, "upload_date": "2025-10-20", "is_official": true, "is_original": false, "is_ai_generated": false, "still_on_tiktok": true, "thumbnail_url": "https://p16-common.tiktokcdn-us.com/tos-alisg-v-2774/oIBRCwt8oFHAAtWAIoED2efkIAaSgHxDBQimJZ~tplv-tiktokx-cropcenter:720:720.jpeg", "video_trend": [ { "date": "2026-08-24", "videos": 349649 }, { "date": "2026-08-25", "videos": 350792 } ] } ] } } } } } } } } }, "/api/track/{id}/topVideos": { "get": { "summary": "💎 Premium — List Top TikTok Videos for a Track", "tags": [ "Track" ], "operationId": "listTrackTopTikTokVideos", "description": "Return the top TikTok videos associated with a track. When `type=trending` only, returns trending videos; otherwise the top videos by the selected sort. `cm_id` is populated when the poster is linked to a Chartmetric artist. Each row carries the video caption, cumulative engagement counters, the daily history behind them, and change rates over the comparison window. Page with `limit` and `offset`, narrow with `postedWithinDaysAgo` or the `min`/`max` metric bounds, and set `withTotal=true` to receive the rows inside an envelope carrying `total` and `available_count` rather than as a bare array.", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric track ID." }, "required": true, "description": "Chartmetric track ID.", "examples": { "default": { "value": 1 } } }, { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "likes", "views", "comments", "followers", "created_at", "trending", "modified_at", "saves", "shares" ], "description": "Sort metric for the returned videos. Defaults to `likes`; allowed values come from TikTok engagement stats.", "default": "likes" }, "required": false, "description": "Sort metric for the returned videos. Defaults to `likes`; allowed values come from TikTok engagement stats." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum number of videos to return. Max 100.", "default": 10 }, "required": false, "description": "Maximum number of videos to return. Max 100." }, { "name": "byTiktokId", "in": "query", "schema": { "type": "boolean", "description": "If true, treat `id` as a TikTok sound ID (string-internally) rather than a Chartmetric track ID. Defaults to false.", "default": false }, "required": false, "description": "If true, treat `id` as a TikTok sound ID (string-internally) rather than a Chartmetric track ID. Defaults to false." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Number of videos to skip from the start of the result set, for paging past the first `limit` rows. Defaults to 0, max 10,000." }, "required": false, "description": "Number of videos to skip from the start of the result set, for paging past the first `limit` rows. Defaults to 0, max 10,000." }, { "name": "sortOrderDesc", "in": "query", "schema": { "type": "boolean", "description": "Sort direction for `type`. Defaults to true (highest first).", "default": true }, "required": false, "description": "Sort direction for `type`. Defaults to true (highest first)." }, { "name": "withTotal", "in": "query", "schema": { "type": "boolean", "description": "If true, wrap the videos in an object carrying `total` and `available_count` so a caller can page to the end. Defaults to false, which returns the bare array.", "default": false }, "required": false, "description": "If true, wrap the videos in an object carrying `total` and `available_count` so a caller can page to the end. Defaults to false, which returns the bare array." }, { "name": "postedWithinDaysAgo", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Only return videos posted within this many days. Omit to cover all time." }, "required": false, "description": "Only return videos posted within this many days. Omit to cover all time." }, { "name": "fromDaysAgo", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 365, "description": "Window in days used as the baseline for the change-rate fields. Defaults to 28, max 365.", "default": 28 }, "required": false, "description": "Window in days used as the baseline for the change-rate fields. Defaults to 28, max 365." }, { "name": "minViews", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Only return videos with at least this many views." }, "required": false, "description": "Only return videos with at least this many views." }, { "name": "maxViews", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Only return videos with at most this many views." }, "required": false, "description": "Only return videos with at most this many views." }, { "name": "minLikes", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Only return videos with at least this many likes." }, "required": false, "description": "Only return videos with at least this many likes." }, { "name": "maxLikes", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Only return videos with at most this many likes." }, "required": false, "description": "Only return videos with at most this many likes." }, { "name": "minComments", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Only return videos with at least this many comments." }, "required": false, "description": "Only return videos with at least this many comments." }, { "name": "maxComments", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Only return videos with at most this many comments." }, "required": false, "description": "Only return videos with at most this many comments." }, { "name": "minShares", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Only return videos with at least this many shares." }, "required": false, "description": "Only return videos with at least this many shares." }, { "name": "maxShares", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Only return videos with at most this many shares." }, "required": false, "description": "Only return videos with at most this many shares." }, { "name": "minSaves", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Only return videos with at least this many saves." }, "required": false, "description": "Only return videos with at least this many saves." }, { "name": "maxSaves", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Only return videos with at most this many saves." }, "required": false, "description": "Only return videos with at most this many saves." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "created_at": { "type": [ "string", "null" ], "description": "Date the video was posted, formatted `YYYY-MM-DD HH:mm:ss`." }, "modified_at": { "type": [ "string", "null" ], "description": "Date the video's counters were last refreshed, formatted `YYYY-MM-DD`." }, "username": { "type": [ "string", "null" ], "description": "TikTok username of the video poster." }, "video_id": { "type": [ "string", "null" ], "description": "TikTok video ID." }, "thumbnail_url": { "type": [ "string", "null" ], "description": "URL of the video thumbnail." }, "avatar_url": { "type": [ "string", "null" ], "description": "URL of the poster's profile image. Null when no avatar has been cached." }, "followers": { "type": [ "integer", "null" ], "minimum": 0, "description": "Follower count of the poster at observation time." }, "cm_id": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "nullable": true, "description": "Chartmetric artist ID of the poster when linked. Null if no link is known." }, "link": { "type": [ "string", "null" ], "description": "Direct URL to the TikTok video." }, "description": { "type": [ "string", "null" ], "description": "The video's caption, including hashtags and mentions." }, "influencerCountries": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "ISO 3166-1 alpha-2 country codes inferred for the poster. Empty when no country is known." }, "sound_id": { "type": [ "string", "null" ], "description": "TikTok's ID for the sound used in the video." }, "tiktok": { "type": [ "integer", "null" ], "description": "Chartmetric's internal ID for that sound." }, "cm_track": { "type": [ "integer", "null" ], "description": "Chartmetric track ID the sound resolves to." }, "tiktok_video": { "type": [ "integer", "null" ], "description": "Chartmetric's internal ID for the video." }, "stats": { "type": [ "object", "null" ], "properties": { "likes": { "type": [ "integer", "null" ], "minimum": 0, "description": "Cumulative like count for the video." }, "comments": { "type": [ "integer", "null" ], "minimum": 0, "description": "Cumulative comment count for the video." }, "views": { "type": [ "integer", "null" ], "minimum": 0, "description": "Cumulative view count for the video." }, "shares": { "type": [ "integer", "null" ], "minimum": 0, "description": "Cumulative share count for the video." }, "saves": { "type": [ "integer", "null" ], "minimum": 0, "description": "Cumulative save count for the video." } }, "description": "Engagement stats for the video, as of `modified_at`." }, "tiktokVideoHistoricalStats": { "type": "array", "items": { "type": "object", "properties": { "views": { "type": [ "integer", "null" ], "description": "Views recorded on that date." }, "likes": { "type": [ "integer", "null" ], "description": "Likes recorded on that date." }, "shares": { "type": [ "integer", "null" ], "description": "Shares recorded on that date." }, "saves": { "type": [ "integer", "null" ], "description": "Saves recorded on that date." }, "comments": { "type": [ "integer", "null" ], "description": "Comments recorded on that date." }, "timestp": { "type": [ "string", "null" ], "description": "Date of the snapshot, formatted `YYYY-MM-DD`." } } }, "description": "Daily snapshots of the counters above, oldest first, covering the history held for the video." }, "likesPercentChange": { "type": [ "number", "null" ], "format": "float", "description": "Percent change in likes across the comparison window. Null when the video has too little history to compare." }, "commentsPercentChange": { "type": [ "number", "null" ], "format": "float", "description": "Percent change in comments across the same window." }, "viewsPercentChange": { "type": [ "number", "null" ], "format": "float", "description": "Percent change in views across the same window." }, "sharesPercentChange": { "type": [ "number", "null" ], "format": "float", "description": "Percent change in shares across the same window." }, "savesPercentChange": { "type": [ "number", "null" ], "format": "float", "description": "Percent change in saves across the same window." }, "likesValueChange": { "type": [ "integer", "null" ], "description": "Absolute change in likes across the same window." }, "commentsValueChange": { "type": [ "integer", "null" ], "description": "Absolute change in comments across the same window." }, "viewsValueChange": { "type": [ "integer", "null" ], "description": "Absolute change in views across the same window." }, "sharesValueChange": { "type": [ "integer", "null" ], "description": "Absolute change in shares across the same window." }, "savesValueChange": { "type": [ "integer", "null" ], "description": "Absolute change in saves across the same window." } } } }, { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "created_at": { "type": [ "string", "null" ], "description": "Date the video was posted, formatted `YYYY-MM-DD HH:mm:ss`." }, "modified_at": { "type": [ "string", "null" ], "description": "Date the video's counters were last refreshed, formatted `YYYY-MM-DD`." }, "username": { "type": [ "string", "null" ], "description": "TikTok username of the video poster." }, "video_id": { "type": [ "string", "null" ], "description": "TikTok video ID." }, "thumbnail_url": { "type": [ "string", "null" ], "description": "URL of the video thumbnail." }, "avatar_url": { "type": [ "string", "null" ], "description": "URL of the poster's profile image. Null when no avatar has been cached." }, "followers": { "type": [ "integer", "null" ], "minimum": 0, "description": "Follower count of the poster at observation time." }, "cm_id": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "nullable": true, "description": "Chartmetric artist ID of the poster when linked. Null if no link is known." }, "link": { "type": [ "string", "null" ], "description": "Direct URL to the TikTok video." }, "description": { "type": [ "string", "null" ], "description": "The video's caption, including hashtags and mentions." }, "influencerCountries": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "ISO 3166-1 alpha-2 country codes inferred for the poster. Empty when no country is known." }, "sound_id": { "type": [ "string", "null" ], "description": "TikTok's ID for the sound used in the video." }, "tiktok": { "type": [ "integer", "null" ], "description": "Chartmetric's internal ID for that sound." }, "cm_track": { "type": [ "integer", "null" ], "description": "Chartmetric track ID the sound resolves to." }, "tiktok_video": { "type": [ "integer", "null" ], "description": "Chartmetric's internal ID for the video." }, "stats": { "type": [ "object", "null" ], "properties": { "likes": { "type": [ "integer", "null" ], "minimum": 0, "description": "Cumulative like count for the video." }, "comments": { "type": [ "integer", "null" ], "minimum": 0, "description": "Cumulative comment count for the video." }, "views": { "type": [ "integer", "null" ], "minimum": 0, "description": "Cumulative view count for the video." }, "shares": { "type": [ "integer", "null" ], "minimum": 0, "description": "Cumulative share count for the video." }, "saves": { "type": [ "integer", "null" ], "minimum": 0, "description": "Cumulative save count for the video." } }, "description": "Engagement stats for the video, as of `modified_at`." }, "tiktokVideoHistoricalStats": { "type": "array", "items": { "type": "object", "properties": { "views": { "type": [ "integer", "null" ], "description": "Views recorded on that date." }, "likes": { "type": [ "integer", "null" ], "description": "Likes recorded on that date." }, "shares": { "type": [ "integer", "null" ], "description": "Shares recorded on that date." }, "saves": { "type": [ "integer", "null" ], "description": "Saves recorded on that date." }, "comments": { "type": [ "integer", "null" ], "description": "Comments recorded on that date." }, "timestp": { "type": [ "string", "null" ], "description": "Date of the snapshot, formatted `YYYY-MM-DD`." } } }, "description": "Daily snapshots of the counters above, oldest first, covering the history held for the video." }, "likesPercentChange": { "type": [ "number", "null" ], "format": "float", "description": "Percent change in likes across the comparison window. Null when the video has too little history to compare." }, "commentsPercentChange": { "type": [ "number", "null" ], "format": "float", "description": "Percent change in comments across the same window." }, "viewsPercentChange": { "type": [ "number", "null" ], "format": "float", "description": "Percent change in views across the same window." }, "sharesPercentChange": { "type": [ "number", "null" ], "format": "float", "description": "Percent change in shares across the same window." }, "savesPercentChange": { "type": [ "number", "null" ], "format": "float", "description": "Percent change in saves across the same window." }, "likesValueChange": { "type": [ "integer", "null" ], "description": "Absolute change in likes across the same window." }, "commentsValueChange": { "type": [ "integer", "null" ], "description": "Absolute change in comments across the same window." }, "viewsValueChange": { "type": [ "integer", "null" ], "description": "Absolute change in views across the same window." }, "sharesValueChange": { "type": [ "integer", "null" ], "description": "Absolute change in shares across the same window." }, "savesValueChange": { "type": [ "integer", "null" ], "description": "Absolute change in saves across the same window." } } }, "description": "The videos on this page." }, "total": { "type": [ "integer", "null" ], "minimum": 0, "description": "Videos matching the current filters across all pages." }, "available_count": { "type": [ "integer", "null" ], "minimum": 0, "description": "Same value as `total`. The handler populates both from one filtered count; kept for callers already reading it." }, "lasted_updated_at": { "type": [ "string", "null" ], "description": "Date the track's videos were last refreshed. The field name carries a long-standing typo." } } } ], "description": "A bare array by default; the envelope above when `withTotal=true`." } }, "additionalProperties": false }, "examples": { "default": { "value": { "obj": [ { "created_at": "2026-05-11 00:00:00", "modified_at": "2026-08-19", "username": "haileybieber", "followers": 19338972, "video_id": "7638754937748360478", "cm_id": 11647783, "sound_id": "x-7559312683885201425", "tiktok": 25646255, "cm_track": 154524166, "tiktok_video": 845854366, "influencerCountries": [ "US" ], "avatar_url": "https://d2xuw6r9djpzwq.cloudfront.net/tiktok/users/6772347709954851846.jpg", "link": "https://www.tiktok.com/@haileybieber/video/7638754937748360478", "stats": { "likes": 3056560, "comments": 13728, "views": 27629256, "shares": 74701, "saves": 138553 }, "description": "Choosin' Texas", "thumbnail_url": "https://d2xuw6r9djpzwq.cloudfront.net/tiktok/videos/7638754937748360478.jpg", "tiktokVideoHistoricalStats": [ { "views": 25600000, "likes": 2900000, "shares": 73100, "saves": 133600, "comments": 13300, "timestp": "2026-07-08" }, { "views": 25700000, "likes": 2900000, "shares": 73200, "saves": 133900, "comments": 13300, "timestp": "2026-07-09" } ], "likesPercentChange": null, "commentsPercentChange": null, "viewsPercentChange": null, "sharesPercentChange": null, "savesPercentChange": null, "likesValueChange": null, "commentsValueChange": null, "viewsValueChange": null, "sharesValueChange": null, "savesValueChange": null } ] } } } } } } } } }, "/api/track/{id}/relatedTracks": { "get": { "summary": "List Related Tracks", "tags": [ "Track" ], "operationId": "listTrackRelatedTracks", "description": "Return related tracks — remixes, live versions, remasters, and other cluster members. Each entry carries the same basic info shape as `GET /api/track/{id}` plus cluster flags.", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric track ID." }, "required": true, "description": "Chartmetric track ID.", "examples": { "default": { "value": 1 } } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Related track's Chartmetric track ID." }, "name": { "type": [ "string", "null" ], "description": "Related track's title." }, "image_url": { "type": [ "string", "null" ], "description": "URL of the related track's artwork." }, "isrc": { "type": [ "string", "null" ], "description": "Related track's ISRC." }, "is_most_popular_cm_track": { "type": "boolean", "description": "True if this version is the most popular among all cluster members." }, "is_earliest_cm_track": { "type": "boolean", "description": "True if this version is the earliest ingested among all cluster members." }, "cluster_type": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Cluster classification flags (e.g. 'remix', 'live', 'remaster'). Empty for the original." } }, "required": [ "id", "is_most_popular_cm_track", "is_earliest_cm_track" ] } } }, "additionalProperties": false }, "examples": { "default": { "value": { "obj": [ { "id": 31826159, "name": "34+35", "image_url": "https://i.scdn.co/image/ab67616d0000b273ba23b8f2fcaa9bc762e37865", "isrc": "USUM72020424", "is_most_popular_cm_track": false, "is_earliest_cm_track": false, "cluster_type": [] }, { "id": 32564030, "name": "34+35 (Remix) [feat. Doja Cat & Megan Thee Stallion]", "image_url": "https://is4-ssl.mzstatic.com/image/thumb/Music114/v4/b4/b3/95/b4b39515-3c23-de6f-521e-d5beb3a31d7d/20UM1IM17687.rgb.jpg/160x160bb.jpeg", "isrc": "USUM72024484", "is_most_popular_cm_track": true, "is_earliest_cm_track": true, "cluster_type": [ "remix" ] } ] } } } } } } } } }, "/api/track/{id}/{platform}/{status}/playlists": { "get": { "summary": "List Playlists Containing a Track", "tags": [ "Track" ], "operationId": "listTrackPlaylists", "description": "Return playlists that currently (or previously) contain a track. `platform` accepts `spotify`, `applemusic` (aliased to `itunes`), `deezer`, `amazon`, `soundcloud`. `status` is `current` or `past`.\n\n**Allowed `sortColumn` per (`platform`, `status`):**\n\n| platform | status | Valid `sortColumn` values |\n|---|---|---|\n| spotify | current | `added_at`, `fdiff_month`, `followers` (default), `name`, `position`, `peak_position`, `track`, `code2` |\n| spotify | past | `added_at`, `fdiff_month`, `followers` (default), `name`, `position`, `peak_position`, `removed_at`, `track`, `code2` |\n| applemusic | current | `added_at` (default), `name`, `position`, `peak_position` |\n| applemusic | past | `added_at`, `name`, `position`, `peak_position`, `removed_at` (default) |\n| deezer | current | `added_at` (default), `fdiff_month`, `followers`, `name`, `peak_position` |\n| deezer | past | `added_at`, `fdiff_month`, `followers`, `name`, `peak_position`, `removed_at` (default) |\n| amazon | current | `added_at` (default), `countries`, `name`, `peak_position` |\n| amazon | past | `added_at`, `peak_position`, `removed_at` (default) |\n| soundcloud | current | `added_at`, `fdiff_month`, `likes`, `peak_position` |\n| soundcloud | past | `added_at`, `fdiff_month`, `likes`, `peak_position` |\n\n**Boolean flag parameters supported per platform:**\n\n| Flag | spotify | applemusic | deezer | amazon |\n|---|:---:|:---:|:---:|:---:|\n| `editorial` | ✅ | ✅ | ✅ | |\n| `editorialBrand` | | ✅ | | |\n| `personalized` | ✅ | | | |\n| `deezerPartner` | | | ✅ | |\n| `chart` | ✅ | ✅ | ✅ | |\n| `thisIs` | ✅ | | | |\n| `hundredPercent` | | | ✅ | |\n| `newMusicFriday` | ✅ | | | |\n| `radio` | ✅ | ✅ | | |\n| `fullyPersonalized` | ✅ | | | |\n| `brand` | ✅ | | ✅ | |\n| `majorCurator` | ✅ | | ✅ | |\n| `musicBrand` | | ✅ | | |\n| `nonMusicBrand` | | ✅ | | |\n| `popularIndie` | ✅ | | ✅ | |\n| `indie` | ✅ | ✅ | ✅ | |\n| `audiobook` | ✅ | | | |\n| `personalityArtist` | | ✅ | | |\n\nAmazon does not accept any flags. Flags are not mutually exclusive — pass others as `false` to scope to one. When no flags are specified the API may return an empty array; specify flags explicitly to get data.", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric track ID." }, "required": true, "description": "Chartmetric track ID.", "examples": { "default": { "value": 1 } } }, { "name": "platform", "in": "path", "schema": { "type": "string", "enum": [ "spotify", "applemusic", "deezer", "amazon", "soundcloud" ], "description": "Streaming platform. One of `spotify`, `applemusic` (aliased to `itunes`), `deezer`, `amazon`, `soundcloud`." }, "required": true, "description": "Streaming platform. One of `spotify`, `applemusic` (aliased to `itunes`), `deezer`, `amazon`, `soundcloud`.", "examples": { "default": { "value": "spotify" } } }, { "name": "status", "in": "path", "schema": { "type": "string", "enum": [ "current", "past" ], "description": "Whether to return playlists the track is `current`ly on or has been removed from (`past`)." }, "required": true, "description": "Whether to return playlists the track is `current`ly on or has been removed from (`past`).", "examples": { "default": { "value": "current" } } }, { "name": "since", "in": "query", "schema": { "type": "string", "format": "date", "description": "Inclusive start of the added/removed-at date range in `YYYY-MM-DD` format. Defaults to 180 days before today.", "default": "2026-05-09" }, "required": false, "description": "Inclusive start of the added/removed-at date range in `YYYY-MM-DD` format. Defaults to 180 days before today." }, { "name": "until", "in": "query", "schema": { "type": "string", "format": "date", "description": "Inclusive end of the added/removed-at date range in `YYYY-MM-DD` format. Defaults to today.", "default": "2026-11-05" }, "required": false, "description": "Inclusive end of the added/removed-at date range in `YYYY-MM-DD` format. Defaults to today." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, "required": false, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum number of playlists to return. Max 100.", "default": 10 }, "required": false, "description": "Maximum number of playlists to return. Max 100." }, { "name": "indie", "in": "query", "schema": { "type": "boolean", "description": "Filter to only playlists tagged as indie (independently curated)." }, "required": false, "description": "Filter to only playlists tagged as indie (independently curated)." }, { "name": "majorCurator", "in": "query", "schema": { "type": "boolean", "description": "Filter to only playlists owned by a major-label curator (Sony, Universal, Warner, etc.)." }, "required": false, "description": "Filter to only playlists owned by a major-label curator (Sony, Universal, Warner, etc.)." }, { "name": "editorial", "in": "query", "schema": { "type": "boolean", "description": "Filter to only editorial playlists curated by the platform (e.g. Spotify-owned). Defaults to true; pass `false` to include user-curated playlists.", "default": true }, "required": false, "description": "Filter to only editorial playlists curated by the platform (e.g. Spotify-owned). Defaults to true; pass `false` to include user-curated playlists." }, { "name": "newMusicFriday", "in": "query", "schema": { "type": "boolean", "description": "Filter to only New Music Friday-style new-release playlists." }, "required": false, "description": "Filter to only New Music Friday-style new-release playlists." }, { "name": "editorialBrand", "in": "query", "schema": { "type": "boolean", "description": "Filter to only editorial playlists operated by a brand (e.g. retailer or media outlet)." }, "required": false, "description": "Filter to only editorial playlists operated by a brand (e.g. retailer or media outlet)." }, { "name": "personalized", "in": "query", "schema": { "type": "boolean", "description": "Filter to only personalized playlists (e.g. Discover Weekly, Release Radar). May vary per listener." }, "required": false, "description": "Filter to only personalized playlists (e.g. Discover Weekly, Release Radar). May vary per listener." }, { "name": "deezerPartner", "in": "query", "schema": { "type": "boolean", "description": "Filter to only Deezer partner-curated playlists." }, "required": false, "description": "Filter to only Deezer partner-curated playlists." }, { "name": "chart", "in": "query", "schema": { "type": "boolean", "description": "Filter to only chart playlists (e.g. Top 50, Viral 50). Reflects platform-published rankings." }, "required": false, "description": "Filter to only chart playlists (e.g. Top 50, Viral 50). Reflects platform-published rankings." }, { "name": "thisIs", "in": "query", "schema": { "type": "boolean", "description": "Filter to only artist-spotlight playlists in the 'This Is X' format." }, "required": false, "description": "Filter to only artist-spotlight playlists in the 'This Is X' format." }, { "name": "hundredPercent", "in": "query", "schema": { "type": "boolean", "description": "Filter to only playlists composed entirely of one artist's catalog." }, "required": false, "description": "Filter to only playlists composed entirely of one artist's catalog." }, { "name": "radio", "in": "query", "schema": { "type": "boolean", "description": "Filter to only algorithmic radio-style playlists generated from a seed track or artist." }, "required": false, "description": "Filter to only algorithmic radio-style playlists generated from a seed track or artist." }, { "name": "fullyPersonalized", "in": "query", "schema": { "type": "boolean", "description": "Filter to only fully personalized playlists where the entire tracklist is unique per listener." }, "required": false, "description": "Filter to only fully personalized playlists where the entire tracklist is unique per listener." }, { "name": "brand", "in": "query", "schema": { "type": "boolean", "description": "Filter to only brand-operated playlists (any flavor — music, non-music, retailer, media)." }, "required": false, "description": "Filter to only brand-operated playlists (any flavor — music, non-music, retailer, media)." }, { "name": "musicBrand", "in": "query", "schema": { "type": "boolean", "description": "Filter to only music-industry brand playlists (labels, music publications)." }, "required": false, "description": "Filter to only music-industry brand playlists (labels, music publications)." }, { "name": "nonMusicBrand", "in": "query", "schema": { "type": "boolean", "description": "Filter to only non-music-industry brand playlists (retailers, media outlets, lifestyle)." }, "required": false, "description": "Filter to only non-music-industry brand playlists (retailers, media outlets, lifestyle)." }, { "name": "popularIndie", "in": "query", "schema": { "type": "boolean", "description": "Filter to only popular indie playlists with significant follower count." }, "required": false, "description": "Filter to only popular indie playlists with significant follower count." }, { "name": "audiobook", "in": "query", "schema": { "type": "boolean", "description": "Filter to only audiobook playlists." }, "required": false, "description": "Filter to only audiobook playlists." }, { "name": "personalityArtist", "in": "query", "schema": { "type": "boolean", "description": "Filter to only playlists curated by personality artists (artists with cultural influence beyond their music)." }, "required": false, "description": "Filter to only playlists curated by personality artists (artists with cultural influence beyond their music)." }, { "name": "sortColumn", "in": "query", "schema": { "type": "string", "description": "Column to sort by; allowed values vary by `platform` and `status` (e.g. `added_at`, `followers`, `peak_position`)." }, "required": false, "description": "Column to sort by; allowed values vary by `platform` and `status` (e.g. `added_at`, `followers`, `peak_position`)." }, { "name": "sortOrderDesc", "in": "query", "schema": { "type": "boolean", "description": "If true, sort descending by `sortColumn`. Only valid when `sortColumn` is set. Defaults to true.", "default": true }, "required": false, "description": "If true, sort descending by `sortColumn`. Only valid when `sortColumn` is set. Defaults to true." }, { "name": "minFollowers", "in": "query", "schema": { "type": "integer", "description": "Restrict to playlists with at least this many followers. Defaults to 0 (no filter)." }, "required": false, "description": "Restrict to playlists with at least this many followers. Defaults to 0 (no filter)." }, { "name": "showPositionStats", "in": "query", "schema": { "type": "boolean", "description": "If true, include the track's position-history aggregates (peak position, current position) on each entry. Defaults to false.", "default": false }, "required": false, "description": "If true, include the track's position-history aggregates (peak position, current position) on each entry. Defaults to false." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "playlist": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "description": "Chartmetric playlist ID." }, "name": { "type": [ "string", "null" ], "description": "Playlist name." }, "playlist_id": { "type": [ "string", "null" ], "description": "Native playlist ID on the source platform (e.g. Spotify playlist URI suffix)." }, "description": { "type": [ "string", "null" ], "description": "Playlist description as set by the curator." }, "image_url": { "type": [ "string", "null" ], "description": "URL of the playlist cover artwork." }, "sys_last_updated": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp of the last Chartmetric stats refresh for this playlist." }, "last_updated": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp of the last upstream playlist update from the platform." }, "personalized": { "type": [ "boolean", "null" ], "description": "True if the playlist is personalized (e.g. Discover Weekly, Release Radar) and varies per listener." }, "code2": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-2 country code where the playlist is targeted (e.g. 'US')." }, "owner_name": { "type": [ "string", "null" ], "description": "Display name of the playlist curator/owner." }, "owner_id": { "type": [ "integer", "null" ], "description": "Chartmetric curator ID of the playlist owner." }, "user_id": { "type": [ "string", "null" ], "description": "Native user ID of the playlist owner on the source platform." }, "editorial": { "type": [ "boolean", "null" ], "description": "True if the playlist is curated by an official editorial team. Applies to Spotify, Apple Music, and Deezer." }, "tags": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Chartmetric tag ID." }, "name": { "type": "string", "description": "Tag name (e.g. genre or mood label)." } } }, "description": "Genre/mood tags applied to the playlist." }, "followers": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Current follower count of the playlist. May arrive as numeric or string." }, "num_track": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Number of tracks in the playlist. May arrive as numeric or string." }, "fdiff_week": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Week-over-week change in followers (`followers` minus the count seven days ago)." }, "fdiff_month": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "nullable": true, "description": "Month-over-month change in followers (`followers` minus the count thirty days ago)." }, "catalog": { "type": [ "string", "null" ], "description": "Catalog classification for the playlist (e.g. `catalogue`, `current`)." }, "active_ratio": { "type": [ "number", "null" ], "format": "float", "description": "Fraction (0–1) of the playlist tracks that are recently active per Chartmetric heuristics." } }, "description": "Playlist metadata." }, "track": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "description": "Chartmetric track ID." }, "cm_track": { "type": "integer", "description": "Chartmetric track ID. Same value as `id`." }, "name": { "type": [ "string", "null" ], "description": "Track title." }, "isrc": { "type": [ "string", "null" ], "description": "International Standard Recording Code identifying the recording." }, "image_url": { "type": [ "string", "null" ], "description": "URL of the track artwork." }, "spotify_popularity": { "type": [ "integer", "null" ], "description": "Spotify popularity score (0–100, higher is more popular)." }, "spotify_duration_ms": { "type": [ "integer", "null" ], "description": "Track duration on Spotify in milliseconds." }, "cm_artist": { "type": [ "array", "null" ], "items": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "description": "Chartmetric artist IDs of the credited artists, ordered by main-artist-first." }, "artist_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Display names of the credited artists, aligned with `cm_artist`." }, "spotify_artist_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Spotify artist IDs of the credited artists." }, "spotify_artist_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Spotify display names of the credited artists." }, "spotify_track_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Spotify track IDs linked to this Chartmetric track." }, "spotify_album_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Spotify album IDs containing this track." }, "itunes_artist_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "iTunes/Apple Music artist IDs of the credited artists." }, "itunes_artist_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "iTunes/Apple Music display names of the credited artists." }, "itunes_track_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "iTunes/Apple Music track IDs linked to this Chartmetric track." }, "itunes_album_ids": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "iTunes/Apple Music album IDs containing this track." }, "code2s": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "ISO 3166-1 alpha-2 country codes associated with the credited artists (e.g. 'US', 'BR')." }, "artist_images": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Profile image URLs of the credited artists." }, "artist_covers": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Cover/banner image URLs of the credited artists." }, "album_ids": { "type": [ "array", "null" ], "items": { "type": [ "integer", "null" ] }, "description": "Chartmetric album IDs that contain this track." }, "album_names": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Album titles aligned with `album_ids`." }, "album_upc": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Universal Product Codes for the albums in `album_ids`." }, "album_label": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Record labels for the albums in `album_ids`." }, "release_dates": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Release dates for the albums in `album_ids`, in `YYYY-MM-DD` or ISO-8601 form." }, "storefronts": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "Apple Music storefront codes where the track was charted." }, "track_genre": { "anyOf": [ { "type": "string" }, { "type": "array", "items": {} } ], "nullable": true, "description": "Genre labels for the track. Either a comma-separated string or an array, depending on source." } }, "description": "Position-and-track metadata for the playlist-track pairing." } } } }, { "type": "object", "properties": { "entries": { "type": "array", "items": { "type": "object", "properties": {} }, "description": "Page of playlist entries when `showPositionStats=true` returns the paginated form." }, "total": { "type": "integer", "description": "Total number of matching playlists across all pages." } } } ] } }, "additionalProperties": false }, "examples": { "default": { "value": { "obj": [ { "playlist": { "playlist_id": "37i9dQZF1DWTkxQvqMy4WW", "id": 1635107, "name": "Chillin' on a Dirt Road", "description": "Country music to get you back to the basics.", "image_url": "https://i.scdn.co/image/ab67706f00000003ac122bacaf283ff31b362030", "sys_last_updated": "2023-10-24T00:00:00.000Z", "last_updated": "2023-10-24T00:40:14.000Z", "personalized": true, "code2": "US", "owner_name": "Spotify", "owner_id": 2, "user_id": "spotify", "editorial": false, "tags": [ { "id": 462895, "name": "Country" }, { "id": 462882, "name": "Pop" } ], "followers": 3337655, "num_track": 100, "fdiff_week": 3631, "fdiff_month": 4528, "catalog": "catalogue ", "active_ratio": 0.83 }, "track": { "id": 4445159, "name": "What Ifs (feat. Lauren Alaina)", "isrc": "USRN11600859", "image_url": "https://i.scdn.co/image/3c29df3f40b15", "spotify_popularity": 75, "cm_track": 15711334, "spotify_artist_names": [ "Kane Brown", "Lauren Alaina" ], "track_genre": "contemporary country,country", "cm_artist": [ 5408, 3836 ], "artist_names": [ "Kane Brown", "Lauren Alaina" ], "code2s": [ "US", "US" ], "artist_images": [ "https://i.scdn.co/image/ab676161000051747b44d30c0a151c78d3c0bcaa", "https://i.scdn.co/image/ab6761610000517430be9c1d7921b1229c8b36ad" ], "spotify_artist_ids": [ "3oSJ7TBVCWMDMiYjXNiCKE", "1v3tdpIdBSW14rHUfiEVOv" ], "spotify_track_ids": [ "7zVCrzzEJU7u24sbJPXA5W" ], "spotify_album_ids": [ "4hhvgHjPqUOAYkclDkhL2T" ], "spotify_duration_ms": 188253, "album_ids": [ 1780125 ], "album_names": [ "Kane Brown" ], "album_upc": [ "886445733945" ], "album_label": [ "RCA Records Label Nashville" ], "release_dates": [ "2016-12-02" ] } } ] } } } } } } } } }, "/api/track/{id}/milestones": { "get": { "summary": "List Milestones for a Track", "tags": [ "Track" ], "operationId": "listTrackMilestones", "description": "Return milestone events (chart adds, playlist adds, threshold crossings, etc.) for a track, ranked by star count by default. Use `grouped=true` or `group=` to paginate within categories.", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric track ID." }, "required": true, "description": "Chartmetric track ID.", "examples": { "default": { "value": 1 } } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "description": "Maximum number of milestones to return. Defaults to 100.", "default": 100 }, "required": false, "description": "Maximum number of milestones to return. Defaults to 100." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, "required": false, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, { "name": "stars[]", "in": "query", "schema": { "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 5 }, "description": "Restrict to milestones with star counts in this set (e.g. `[1, 2, 3]`). Each value is between 1 and 5." }, "required": false, "description": "Restrict to milestones with star counts in this set (e.g. `[1, 2, 3]`). Each value is between 1 and 5." }, { "name": "fromDaysAgo", "in": "query", "schema": { "type": "integer", "description": "Restrict to milestones from the last N days, counted from today." }, "required": false, "description": "Restrict to milestones from the last N days, counted from today." }, { "name": "sortColumn", "in": "query", "schema": { "type": "string", "enum": [ "date", "stars" ], "description": "Column to sort milestones by. One of `date`, `stars`. Defaults to `date`.", "default": "date" }, "required": false, "description": "Column to sort milestones by. One of `date`, `stars`. Defaults to `date`." }, { "name": "sortOrderDesc", "in": "query", "schema": { "type": "boolean", "description": "If true, sort descending by `sortColumn`. Defaults to true.", "default": true }, "required": false, "description": "If true, sort descending by `sortColumn`. Defaults to true." }, { "name": "platforms[]", "in": "query", "schema": { "type": "array", "items": { "type": "string", "enum": [ "amazon", "apple_music", "beatport", "chartmetric", "deezer", "instagram", "itunes", "pandora", "shazam", "soundcloud", "spotify", "tiktok", "youtube" ], "title": "Platform name" }, "description": "Restrict to milestones from these platforms (e.g. `Spotify`, `YouTube`)." }, "required": false, "description": "Restrict to milestones from these platforms (e.g. `Spotify`, `YouTube`)." }, { "name": "grouped", "in": "query", "schema": { "type": "boolean", "description": "If true, return only the top milestone per group (e.g. one per chart). Defaults to false." }, "required": false, "description": "If true, return only the top milestone per group (e.g. one per chart). Defaults to false." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "object", "properties": { "insights": { "type": "array", "items": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "description": "Milestone ID. May arrive as numeric or string." }, "date": { "type": [ "string", "null" ], "format": "date-time", "description": "Date the milestone was achieved." }, "summary": { "type": [ "string", "null" ], "description": "Human-readable description of the milestone, matching the artist profile UI." }, "artist_name": { "type": [ "string", "null" ], "description": "Display name of the artist credited on the milestone." }, "track_name": { "type": [ "string", "null" ], "description": "Track title associated with the milestone." }, "platform": { "type": [ "string", "null" ], "description": "Platform that triggered the milestone (e.g. 'Spotify', 'YouTube')." }, "stars": { "type": [ "integer", "null" ], "description": "Importance score (1–5; higher is more notable)." } } }, "description": "Milestone events for the track, ranked by importance and date." }, "count": { "type": [ "integer", "null" ], "minimum": 0, "description": "Total number of milestones in the result set." } }, "required": [ "insights" ] } }, "additionalProperties": false }, "examples": { "default": { "value": { "obj": { "insights": [ { "id": 1754976786, "date": "2024-04-29", "summary": "Run added to Spotify Top 50 - Vietnam at position 5 with 90.5K followers.", "artist_name": "BTS", "track_name": "Run", "platform": "Spotify", "stars": 4 } ], "count": 14 } } } } } } } } } }, "/api/track/list/filter": { "get": { "summary": "List Tracks with Filters", "tags": [ "Track" ], "operationId": "listTracksByFilter", "description": "Paginated track listing with range filters on dozens of platform stats and sorting on `.` columns.\n\n**Available stats:**\n\n`score`, `release_date`, `airplay_streams`, `amazon_playlist_count`, `deezer_playlist_count`, `itunes_playlist_count`, `shazam_count`, `siriusxm_streams`, `soundcloud_plays`, `spotify_playlist_count`, `spotify_playlist_total_reach`, `spotify_plays`, `spotify_popularity`, `spotify_ed_playlist_count`, `tidal_popularity`, `tiktok_posts`, `tiktok_top_videos_likes`, `tiktok_top_videos_views`, `youtube_likes`, `youtube_playlist_count`, `youtube_views`, `rank`.\n\n**Periods (`range_period`):**\n\n| Period | Meaning |\n|---|---|\n| `latest` | Latest available value |\n| `weekly_diff` | Change in the last 7 days |\n| `monthly_diff` | Change in the last 28 days |\n| `weekly_diff_percent` | Change in the last 7 days, as a percentage |\n| `monthly_diff_percent` | Change in the last 28 days, as a percentage |\n\n`score` and `release_date` have no period — pass them bare (e.g. `sortColumn=score`, `min_release_date=...`). All other stats associate with the selected `range_period`.\n\n**Sorting:** pass `sortColumn=.` (e.g. `weekly_diff.youtube_views`).\n\n**Range filters:** for each stat there is a `min_` and `max_` parameter applied within the active `range_period` (e.g. `range_period=latest&max_tiktok_posts=100` filters tracks with current TikTok posts under 100). `min_release_date` and `max_release_date` apply regardless of `range_period`. Negative values are allowed.\n\nTo use the `version_only`, `version_and`, `version_or`, `version_not` cluster filters, set `originalsOnly=false`.\n\n**Row shape:** each entry contains `cm_track`, `name`, `isrc`, `score`, `image_url`, `explicit`, `genre`, `songwriter`, `moods`, nested `album[]` and `artist[]` arrays, plus a `.` map per requested period (`latest`, `weekly_diff`, `monthly_diff`, etc.).", "parameters": [ { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 10000, "description": "Number of items to skip from the start of the result set. `offset + limit` must not exceed 10000." }, "required": false, "description": "Number of items to skip from the start of the result set. `offset + limit` must not exceed 10000." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 0, "description": "Maximum number of tracks to return. Defaults to 50; max 10000.", "default": 50 }, "required": false, "description": "Maximum number of tracks to return. Defaults to 50; max 10000." }, { "name": "sortOrderDesc", "in": "query", "schema": { "type": "boolean", "description": "If true, sort descending by `sortColumn`. Defaults to true.", "default": true }, "required": false, "description": "If true, sort descending by `sortColumn`. Defaults to true." }, { "name": "sortColumn", "in": "query", "schema": { "type": "string", "enum": [ "score", "album.release_date", "rank.rank_overall", "rank", "airplay_streams", "amazon_playlist_count", "deezer_playlist_count", "itunes_playlist_count", "shazam_count", "siriusxm_streams", "soundcloud_plays", "spotify_playlist_count", "spotify_playlist_total_reach", "spotify_plays", "spotify_popularity", "spotify_ed_playlist_count", "spotify_ed_playlist_total_reach", "tiktok_posts", "tiktok_top_videos_likes", "tiktok_top_videos_views", "youtube_likes", "youtube_playlist_count", "youtube_views", "release_date", "latest.rank", "latest.airplay_streams", "latest.amazon_playlist_count", "latest.deezer_playlist_count", "latest.itunes_playlist_count", "latest.shazam_count", "latest.siriusxm_streams", "latest.soundcloud_plays", "latest.spotify_playlist_count", "latest.spotify_playlist_total_reach", "latest.spotify_plays", "latest.spotify_popularity", "latest.spotify_ed_playlist_count", "latest.spotify_ed_playlist_total_reach", "latest.tiktok_posts", "latest.tiktok_top_videos_likes", "latest.tiktok_top_videos_views", "latest.youtube_likes", "latest.youtube_playlist_count", "latest.youtube_views", "latest.release_date", "weekly_diff.rank", "weekly_diff.airplay_streams", "weekly_diff.amazon_playlist_count", "weekly_diff.deezer_playlist_count", "weekly_diff.itunes_playlist_count", "weekly_diff.shazam_count", "weekly_diff.siriusxm_streams", "weekly_diff.soundcloud_plays", "weekly_diff.spotify_playlist_count", "weekly_diff.spotify_playlist_total_reach", "weekly_diff.spotify_plays", "weekly_diff.spotify_popularity", "weekly_diff.spotify_ed_playlist_count", "weekly_diff.spotify_ed_playlist_total_reach", "weekly_diff.tiktok_posts", "weekly_diff.tiktok_top_videos_likes", "weekly_diff.tiktok_top_videos_views", "weekly_diff.youtube_likes", "weekly_diff.youtube_playlist_count", "weekly_diff.youtube_views", "weekly_diff.release_date", "monthly_diff.rank", "monthly_diff.airplay_streams", "monthly_diff.amazon_playlist_count", "monthly_diff.deezer_playlist_count", "monthly_diff.itunes_playlist_count", "monthly_diff.shazam_count", "monthly_diff.siriusxm_streams", "monthly_diff.soundcloud_plays", "monthly_diff.spotify_playlist_count", "monthly_diff.spotify_playlist_total_reach", "monthly_diff.spotify_plays", "monthly_diff.spotify_popularity", "monthly_diff.spotify_ed_playlist_count", "monthly_diff.spotify_ed_playlist_total_reach", "monthly_diff.tiktok_posts", "monthly_diff.tiktok_top_videos_likes", "monthly_diff.tiktok_top_videos_views", "monthly_diff.youtube_likes", "monthly_diff.youtube_playlist_count", "monthly_diff.youtube_views", "monthly_diff.release_date", "bimonthly_diff.rank", "bimonthly_diff.airplay_streams", "bimonthly_diff.amazon_playlist_count", "bimonthly_diff.deezer_playlist_count", "bimonthly_diff.itunes_playlist_count", "bimonthly_diff.shazam_count", "bimonthly_diff.siriusxm_streams", "bimonthly_diff.soundcloud_plays", "bimonthly_diff.spotify_playlist_count", "bimonthly_diff.spotify_playlist_total_reach", "bimonthly_diff.spotify_plays", "bimonthly_diff.spotify_popularity", "bimonthly_diff.spotify_ed_playlist_count", "bimonthly_diff.spotify_ed_playlist_total_reach", "bimonthly_diff.tiktok_posts", "bimonthly_diff.tiktok_top_videos_likes", "bimonthly_diff.tiktok_top_videos_views", "bimonthly_diff.youtube_likes", "bimonthly_diff.youtube_playlist_count", "bimonthly_diff.youtube_views", "bimonthly_diff.release_date", "weekly_diff_percent.rank", "weekly_diff_percent.airplay_streams", "weekly_diff_percent.amazon_playlist_count", "weekly_diff_percent.deezer_playlist_count", "weekly_diff_percent.itunes_playlist_count", "weekly_diff_percent.shazam_count", "weekly_diff_percent.siriusxm_streams", "weekly_diff_percent.soundcloud_plays", "weekly_diff_percent.spotify_playlist_count", "weekly_diff_percent.spotify_playlist_total_reach", "weekly_diff_percent.spotify_plays", "weekly_diff_percent.spotify_popularity", "weekly_diff_percent.spotify_ed_playlist_count", "weekly_diff_percent.spotify_ed_playlist_total_reach", "weekly_diff_percent.tiktok_posts", "weekly_diff_percent.tiktok_top_videos_likes", "weekly_diff_percent.tiktok_top_videos_views", "weekly_diff_percent.youtube_likes", "weekly_diff_percent.youtube_playlist_count", "weekly_diff_percent.youtube_views", "weekly_diff_percent.release_date", "monthly_diff_percent.rank", "monthly_diff_percent.airplay_streams", "monthly_diff_percent.amazon_playlist_count", "monthly_diff_percent.deezer_playlist_count", "monthly_diff_percent.itunes_playlist_count", "monthly_diff_percent.shazam_count", "monthly_diff_percent.siriusxm_streams", "monthly_diff_percent.soundcloud_plays", "monthly_diff_percent.spotify_playlist_count", "monthly_diff_percent.spotify_playlist_total_reach", "monthly_diff_percent.spotify_plays", "monthly_diff_percent.spotify_popularity", "monthly_diff_percent.spotify_ed_playlist_count", "monthly_diff_percent.spotify_ed_playlist_total_reach", "monthly_diff_percent.tiktok_posts", "monthly_diff_percent.tiktok_top_videos_likes", "monthly_diff_percent.tiktok_top_videos_views", "monthly_diff_percent.youtube_likes", "monthly_diff_percent.youtube_playlist_count", "monthly_diff_percent.youtube_views", "monthly_diff_percent.release_date", "bimonthly_diff_percent.rank", "bimonthly_diff_percent.airplay_streams", "bimonthly_diff_percent.amazon_playlist_count", "bimonthly_diff_percent.deezer_playlist_count", "bimonthly_diff_percent.itunes_playlist_count", "bimonthly_diff_percent.shazam_count", "bimonthly_diff_percent.siriusxm_streams", "bimonthly_diff_percent.soundcloud_plays", "bimonthly_diff_percent.spotify_playlist_count", "bimonthly_diff_percent.spotify_playlist_total_reach", "bimonthly_diff_percent.spotify_plays", "bimonthly_diff_percent.spotify_popularity", "bimonthly_diff_percent.spotify_ed_playlist_count", "bimonthly_diff_percent.spotify_ed_playlist_total_reach", "bimonthly_diff_percent.tiktok_posts", "bimonthly_diff_percent.tiktok_top_videos_likes", "bimonthly_diff_percent.tiktok_top_videos_views", "bimonthly_diff_percent.youtube_likes", "bimonthly_diff_percent.youtube_playlist_count", "bimonthly_diff_percent.youtube_views", "bimonthly_diff_percent.release_date" ], "description": "Column to sort by. Defaults to `score`. Stat columns use `.` form (e.g. `latest.spotify_plays`, `weekly_diff_percent.tiktok_posts`).", "default": "score" }, "required": false, "description": "Column to sort by. Defaults to `score`. Stat columns use `.` form (e.g. `latest.spotify_plays`, `weekly_diff_percent.tiktok_posts`)." }, { "name": "genres[]", "in": "query", "schema": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 2147483647, "title": "Genre ID" }, "description": "Restrict to tracks tagged with any of these Chartmetric genre IDs." }, "required": false, "description": "Restrict to tracks tagged with any of these Chartmetric genre IDs." }, { "name": "artists[]", "in": "query", "schema": { "type": "array", "items": { "type": "integer", "minimum": 2, "maximum": 2147483647, "not": { "enum": [ 1 ] }, "description": "Chartmetric artist ID. Note: id=1 ('Various Artists') is rejected.", "title": "Artist ID" }, "description": "Restrict to tracks performed by any of these Chartmetric artist IDs." }, "required": false, "description": "Restrict to tracks performed by any of these Chartmetric artist IDs." }, { "name": "shortListIds[]", "in": "query", "schema": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "uniqueItems": true, "description": "Restrict to tracks belonging to any of these Chartmetric user shortlist IDs." }, "required": false, "description": "Restrict to tracks belonging to any of these Chartmetric user shortlist IDs." }, { "name": "range_period", "in": "query", "schema": { "type": "string", "enum": [ "latest", "weekly_diff", "monthly_diff", "bimonthly_diff", "weekly_diff_percent", "monthly_diff_percent", "bimonthly_diff_percent" ], "description": "Stat window applied to all `min_` / `max_` filters. Defaults to `latest`.", "default": "latest" }, "required": false, "description": "Stat window applied to all `min_` / `max_` filters. Defaults to `latest`." }, { "name": "max_score", "in": "query", "schema": { "type": "number", "format": "float", "description": "Upper bound (inclusive) for `score`. Value of `score` under the window selected by `range_period`." }, "required": false, "description": "Upper bound (inclusive) for `score`. Value of `score` under the window selected by `range_period`." }, { "name": "min_score", "in": "query", "schema": { "type": "number", "format": "float", "description": "Lower bound (inclusive) for `score`. Value of `score` under the window selected by `range_period`." }, "required": false, "description": "Lower bound (inclusive) for `score`. Value of `score` under the window selected by `range_period`." }, { "name": "max_album.release_date", "in": "query", "schema": { "type": "number", "format": "float", "description": "Upper bound (inclusive) for `album.release_date`. Value of `album.release_date` under the window selected by `range_period`." }, "required": false, "description": "Upper bound (inclusive) for `album.release_date`. Value of `album.release_date` under the window selected by `range_period`." }, { "name": "min_album.release_date", "in": "query", "schema": { "type": "number", "format": "float", "description": "Lower bound (inclusive) for `album.release_date`. Value of `album.release_date` under the window selected by `range_period`." }, "required": false, "description": "Lower bound (inclusive) for `album.release_date`. Value of `album.release_date` under the window selected by `range_period`." }, { "name": "max_rank.rank_overall", "in": "query", "schema": { "type": "number", "format": "float", "description": "Upper bound (inclusive) for `rank.rank_overall`. Value of `rank.rank_overall` under the window selected by `range_period`." }, "required": false, "description": "Upper bound (inclusive) for `rank.rank_overall`. Value of `rank.rank_overall` under the window selected by `range_period`." }, { "name": "min_rank.rank_overall", "in": "query", "schema": { "type": "number", "format": "float", "description": "Lower bound (inclusive) for `rank.rank_overall`. Value of `rank.rank_overall` under the window selected by `range_period`." }, "required": false, "description": "Lower bound (inclusive) for `rank.rank_overall`. Value of `rank.rank_overall` under the window selected by `range_period`." }, { "name": "max_rank", "in": "query", "schema": { "type": "number", "format": "float", "description": "Upper bound (inclusive) for `rank`. Value of `rank` under the window selected by `range_period`." }, "required": false, "description": "Upper bound (inclusive) for `rank`. Value of `rank` under the window selected by `range_period`." }, { "name": "min_rank", "in": "query", "schema": { "type": "number", "format": "float", "description": "Lower bound (inclusive) for `rank`. Value of `rank` under the window selected by `range_period`." }, "required": false, "description": "Lower bound (inclusive) for `rank`. Value of `rank` under the window selected by `range_period`." }, { "name": "max_airplay_streams", "in": "query", "schema": { "type": "number", "format": "float", "description": "Upper bound (inclusive) for `airplay_streams`. Value of `airplay_streams` under the window selected by `range_period`." }, "required": false, "description": "Upper bound (inclusive) for `airplay_streams`. Value of `airplay_streams` under the window selected by `range_period`." }, { "name": "min_airplay_streams", "in": "query", "schema": { "type": "number", "format": "float", "description": "Lower bound (inclusive) for `airplay_streams`. Value of `airplay_streams` under the window selected by `range_period`." }, "required": false, "description": "Lower bound (inclusive) for `airplay_streams`. Value of `airplay_streams` under the window selected by `range_period`." }, { "name": "max_amazon_playlist_count", "in": "query", "schema": { "type": "number", "format": "float", "description": "Upper bound (inclusive) for `amazon_playlist_count`. Value of `amazon_playlist_count` under the window selected by `range_period`." }, "required": false, "description": "Upper bound (inclusive) for `amazon_playlist_count`. Value of `amazon_playlist_count` under the window selected by `range_period`." }, { "name": "min_amazon_playlist_count", "in": "query", "schema": { "type": "number", "format": "float", "description": "Lower bound (inclusive) for `amazon_playlist_count`. Value of `amazon_playlist_count` under the window selected by `range_period`." }, "required": false, "description": "Lower bound (inclusive) for `amazon_playlist_count`. Value of `amazon_playlist_count` under the window selected by `range_period`." }, { "name": "max_deezer_playlist_count", "in": "query", "schema": { "type": "number", "format": "float", "description": "Upper bound (inclusive) for `deezer_playlist_count`. Value of `deezer_playlist_count` under the window selected by `range_period`." }, "required": false, "description": "Upper bound (inclusive) for `deezer_playlist_count`. Value of `deezer_playlist_count` under the window selected by `range_period`." }, { "name": "min_deezer_playlist_count", "in": "query", "schema": { "type": "number", "format": "float", "description": "Lower bound (inclusive) for `deezer_playlist_count`. Value of `deezer_playlist_count` under the window selected by `range_period`." }, "required": false, "description": "Lower bound (inclusive) for `deezer_playlist_count`. Value of `deezer_playlist_count` under the window selected by `range_period`." }, { "name": "max_itunes_playlist_count", "in": "query", "schema": { "type": "number", "format": "float", "description": "Upper bound (inclusive) for `itunes_playlist_count`. Value of `itunes_playlist_count` under the window selected by `range_period`." }, "required": false, "description": "Upper bound (inclusive) for `itunes_playlist_count`. Value of `itunes_playlist_count` under the window selected by `range_period`." }, { "name": "min_itunes_playlist_count", "in": "query", "schema": { "type": "number", "format": "float", "description": "Lower bound (inclusive) for `itunes_playlist_count`. Value of `itunes_playlist_count` under the window selected by `range_period`." }, "required": false, "description": "Lower bound (inclusive) for `itunes_playlist_count`. Value of `itunes_playlist_count` under the window selected by `range_period`." }, { "name": "max_shazam_count", "in": "query", "schema": { "type": "number", "format": "float", "description": "Upper bound (inclusive) for `shazam_count`. Value of `shazam_count` under the window selected by `range_period`." }, "required": false, "description": "Upper bound (inclusive) for `shazam_count`. Value of `shazam_count` under the window selected by `range_period`." }, { "name": "min_shazam_count", "in": "query", "schema": { "type": "number", "format": "float", "description": "Lower bound (inclusive) for `shazam_count`. Value of `shazam_count` under the window selected by `range_period`." }, "required": false, "description": "Lower bound (inclusive) for `shazam_count`. Value of `shazam_count` under the window selected by `range_period`." }, { "name": "max_siriusxm_streams", "in": "query", "schema": { "type": "number", "format": "float", "description": "Upper bound (inclusive) for `siriusxm_streams`. Value of `siriusxm_streams` under the window selected by `range_period`." }, "required": false, "description": "Upper bound (inclusive) for `siriusxm_streams`. Value of `siriusxm_streams` under the window selected by `range_period`." }, { "name": "min_siriusxm_streams", "in": "query", "schema": { "type": "number", "format": "float", "description": "Lower bound (inclusive) for `siriusxm_streams`. Value of `siriusxm_streams` under the window selected by `range_period`." }, "required": false, "description": "Lower bound (inclusive) for `siriusxm_streams`. Value of `siriusxm_streams` under the window selected by `range_period`." }, { "name": "max_soundcloud_plays", "in": "query", "schema": { "type": "number", "format": "float", "description": "Upper bound (inclusive) for `soundcloud_plays`. Value of `soundcloud_plays` under the window selected by `range_period`." }, "required": false, "description": "Upper bound (inclusive) for `soundcloud_plays`. Value of `soundcloud_plays` under the window selected by `range_period`." }, { "name": "min_soundcloud_plays", "in": "query", "schema": { "type": "number", "format": "float", "description": "Lower bound (inclusive) for `soundcloud_plays`. Value of `soundcloud_plays` under the window selected by `range_period`." }, "required": false, "description": "Lower bound (inclusive) for `soundcloud_plays`. Value of `soundcloud_plays` under the window selected by `range_period`." }, { "name": "max_spotify_playlist_count", "in": "query", "schema": { "type": "number", "format": "float", "description": "Upper bound (inclusive) for `spotify_playlist_count`. Value of `spotify_playlist_count` under the window selected by `range_period`." }, "required": false, "description": "Upper bound (inclusive) for `spotify_playlist_count`. Value of `spotify_playlist_count` under the window selected by `range_period`." }, { "name": "min_spotify_playlist_count", "in": "query", "schema": { "type": "number", "format": "float", "description": "Lower bound (inclusive) for `spotify_playlist_count`. Value of `spotify_playlist_count` under the window selected by `range_period`." }, "required": false, "description": "Lower bound (inclusive) for `spotify_playlist_count`. Value of `spotify_playlist_count` under the window selected by `range_period`." }, { "name": "max_spotify_playlist_total_reach", "in": "query", "schema": { "type": "number", "format": "float", "description": "Upper bound (inclusive) for `spotify_playlist_total_reach`. Value of `spotify_playlist_total_reach` under the window selected by `range_period`." }, "required": false, "description": "Upper bound (inclusive) for `spotify_playlist_total_reach`. Value of `spotify_playlist_total_reach` under the window selected by `range_period`." }, { "name": "min_spotify_playlist_total_reach", "in": "query", "schema": { "type": "number", "format": "float", "description": "Lower bound (inclusive) for `spotify_playlist_total_reach`. Value of `spotify_playlist_total_reach` under the window selected by `range_period`." }, "required": false, "description": "Lower bound (inclusive) for `spotify_playlist_total_reach`. Value of `spotify_playlist_total_reach` under the window selected by `range_period`." }, { "name": "max_spotify_plays", "in": "query", "schema": { "type": "number", "format": "float", "description": "Upper bound (inclusive) for `spotify_plays`. Value of `spotify_plays` under the window selected by `range_period`." }, "required": false, "description": "Upper bound (inclusive) for `spotify_plays`. Value of `spotify_plays` under the window selected by `range_period`." }, { "name": "min_spotify_plays", "in": "query", "schema": { "type": "number", "format": "float", "description": "Lower bound (inclusive) for `spotify_plays`. Value of `spotify_plays` under the window selected by `range_period`." }, "required": false, "description": "Lower bound (inclusive) for `spotify_plays`. Value of `spotify_plays` under the window selected by `range_period`." }, { "name": "max_spotify_popularity", "in": "query", "schema": { "type": "number", "format": "float", "description": "Upper bound (inclusive) for `spotify_popularity`. Value of `spotify_popularity` under the window selected by `range_period`." }, "required": false, "description": "Upper bound (inclusive) for `spotify_popularity`. Value of `spotify_popularity` under the window selected by `range_period`." }, { "name": "min_spotify_popularity", "in": "query", "schema": { "type": "number", "format": "float", "description": "Lower bound (inclusive) for `spotify_popularity`. Value of `spotify_popularity` under the window selected by `range_period`." }, "required": false, "description": "Lower bound (inclusive) for `spotify_popularity`. Value of `spotify_popularity` under the window selected by `range_period`." }, { "name": "max_spotify_ed_playlist_count", "in": "query", "schema": { "type": "number", "format": "float", "description": "Upper bound (inclusive) for `spotify_ed_playlist_count`. Value of `spotify_ed_playlist_count` under the window selected by `range_period`." }, "required": false, "description": "Upper bound (inclusive) for `spotify_ed_playlist_count`. Value of `spotify_ed_playlist_count` under the window selected by `range_period`." }, { "name": "min_spotify_ed_playlist_count", "in": "query", "schema": { "type": "number", "format": "float", "description": "Lower bound (inclusive) for `spotify_ed_playlist_count`. Value of `spotify_ed_playlist_count` under the window selected by `range_period`." }, "required": false, "description": "Lower bound (inclusive) for `spotify_ed_playlist_count`. Value of `spotify_ed_playlist_count` under the window selected by `range_period`." }, { "name": "max_spotify_ed_playlist_total_reach", "in": "query", "schema": { "type": "number", "format": "float", "description": "Upper bound (inclusive) for `spotify_ed_playlist_total_reach`. Value of `spotify_ed_playlist_total_reach` under the window selected by `range_period`." }, "required": false, "description": "Upper bound (inclusive) for `spotify_ed_playlist_total_reach`. Value of `spotify_ed_playlist_total_reach` under the window selected by `range_period`." }, { "name": "min_spotify_ed_playlist_total_reach", "in": "query", "schema": { "type": "number", "format": "float", "description": "Lower bound (inclusive) for `spotify_ed_playlist_total_reach`. Value of `spotify_ed_playlist_total_reach` under the window selected by `range_period`." }, "required": false, "description": "Lower bound (inclusive) for `spotify_ed_playlist_total_reach`. Value of `spotify_ed_playlist_total_reach` under the window selected by `range_period`." }, { "name": "max_tiktok_posts", "in": "query", "schema": { "type": "number", "format": "float", "description": "Upper bound (inclusive) for `tiktok_posts`. Value of `tiktok_posts` under the window selected by `range_period`." }, "required": false, "description": "Upper bound (inclusive) for `tiktok_posts`. Value of `tiktok_posts` under the window selected by `range_period`." }, { "name": "min_tiktok_posts", "in": "query", "schema": { "type": "number", "format": "float", "description": "Lower bound (inclusive) for `tiktok_posts`. Value of `tiktok_posts` under the window selected by `range_period`." }, "required": false, "description": "Lower bound (inclusive) for `tiktok_posts`. Value of `tiktok_posts` under the window selected by `range_period`." }, { "name": "max_tiktok_top_videos_likes", "in": "query", "schema": { "type": "number", "format": "float", "description": "Upper bound (inclusive) for `tiktok_top_videos_likes`. Value of `tiktok_top_videos_likes` under the window selected by `range_period`." }, "required": false, "description": "Upper bound (inclusive) for `tiktok_top_videos_likes`. Value of `tiktok_top_videos_likes` under the window selected by `range_period`." }, { "name": "min_tiktok_top_videos_likes", "in": "query", "schema": { "type": "number", "format": "float", "description": "Lower bound (inclusive) for `tiktok_top_videos_likes`. Value of `tiktok_top_videos_likes` under the window selected by `range_period`." }, "required": false, "description": "Lower bound (inclusive) for `tiktok_top_videos_likes`. Value of `tiktok_top_videos_likes` under the window selected by `range_period`." }, { "name": "max_tiktok_top_videos_views", "in": "query", "schema": { "type": "number", "format": "float", "description": "Upper bound (inclusive) for `tiktok_top_videos_views`. Value of `tiktok_top_videos_views` under the window selected by `range_period`." }, "required": false, "description": "Upper bound (inclusive) for `tiktok_top_videos_views`. Value of `tiktok_top_videos_views` under the window selected by `range_period`." }, { "name": "min_tiktok_top_videos_views", "in": "query", "schema": { "type": "number", "format": "float", "description": "Lower bound (inclusive) for `tiktok_top_videos_views`. Value of `tiktok_top_videos_views` under the window selected by `range_period`." }, "required": false, "description": "Lower bound (inclusive) for `tiktok_top_videos_views`. Value of `tiktok_top_videos_views` under the window selected by `range_period`." }, { "name": "max_youtube_likes", "in": "query", "schema": { "type": "number", "format": "float", "description": "Upper bound (inclusive) for `youtube_likes`. Value of `youtube_likes` under the window selected by `range_period`." }, "required": false, "description": "Upper bound (inclusive) for `youtube_likes`. Value of `youtube_likes` under the window selected by `range_period`." }, { "name": "min_youtube_likes", "in": "query", "schema": { "type": "number", "format": "float", "description": "Lower bound (inclusive) for `youtube_likes`. Value of `youtube_likes` under the window selected by `range_period`." }, "required": false, "description": "Lower bound (inclusive) for `youtube_likes`. Value of `youtube_likes` under the window selected by `range_period`." }, { "name": "max_youtube_playlist_count", "in": "query", "schema": { "type": "number", "format": "float", "description": "Upper bound (inclusive) for `youtube_playlist_count`. Value of `youtube_playlist_count` under the window selected by `range_period`." }, "required": false, "description": "Upper bound (inclusive) for `youtube_playlist_count`. Value of `youtube_playlist_count` under the window selected by `range_period`." }, { "name": "min_youtube_playlist_count", "in": "query", "schema": { "type": "number", "format": "float", "description": "Lower bound (inclusive) for `youtube_playlist_count`. Value of `youtube_playlist_count` under the window selected by `range_period`." }, "required": false, "description": "Lower bound (inclusive) for `youtube_playlist_count`. Value of `youtube_playlist_count` under the window selected by `range_period`." }, { "name": "max_youtube_views", "in": "query", "schema": { "type": "number", "format": "float", "description": "Upper bound (inclusive) for `youtube_views`. Value of `youtube_views` under the window selected by `range_period`." }, "required": false, "description": "Upper bound (inclusive) for `youtube_views`. Value of `youtube_views` under the window selected by `range_period`." }, { "name": "min_youtube_views", "in": "query", "schema": { "type": "number", "format": "float", "description": "Lower bound (inclusive) for `youtube_views`. Value of `youtube_views` under the window selected by `range_period`." }, "required": false, "description": "Lower bound (inclusive) for `youtube_views`. Value of `youtube_views` under the window selected by `range_period`." }, { "name": "max_release_date", "in": "query", "schema": { "type": "string", "format": "date", "description": "Upper bound (inclusive) for `release_date`. Calendar date (`YYYY-MM-DD`)." }, "required": false, "description": "Upper bound (inclusive) for `release_date`. Calendar date (`YYYY-MM-DD`)." }, { "name": "min_release_date", "in": "query", "schema": { "type": "string", "format": "date", "description": "Lower bound (inclusive) for `release_date`. Calendar date (`YYYY-MM-DD`)." }, "required": false, "description": "Lower bound (inclusive) for `release_date`. Calendar date (`YYYY-MM-DD`)." }, { "name": "originalsOnly", "in": "query", "schema": { "type": "boolean", "description": "If true, return only original recordings (excludes remixes, covers, etc.). Defaults to true. Set to false to enable `version_*` cluster filters.", "default": true }, "required": false, "description": "If true, return only original recordings (excludes remixes, covers, etc.). Defaults to true. Set to false to enable `version_*` cluster filters." }, { "name": "version_only[]", "in": "query", "schema": { "type": "array", "items": { "type": "string", "enum": [ "original", "re_release", "edit", "remix", "acoustic", "alt_ver", "physical_ver", "cover", "live", "feat_or_collab", "dub", "remaster", "bonus", "arrangement", "commentary", "lofi", "component", "karaoke", "compilation_rerelease", "explicit", "clean", "other" ] }, "description": "Return only tracks where every cluster type matches one of these values. Mutually exclusive with `version_and`, `version_or`, `version_not`." }, "required": false, "description": "Return only tracks where every cluster type matches one of these values. Mutually exclusive with `version_and`, `version_or`, `version_not`." }, { "name": "version_and[]", "in": "query", "schema": { "type": "array", "items": { "type": "string", "enum": [ "original", "re_release", "edit", "remix", "acoustic", "alt_ver", "physical_ver", "cover", "live", "feat_or_collab", "dub", "remaster", "bonus", "arrangement", "commentary", "lofi", "component", "karaoke", "compilation_rerelease", "explicit", "clean", "other" ] }, "description": "Return tracks whose cluster contains all of these types. Mutually exclusive with `version_or`." }, "required": false, "description": "Return tracks whose cluster contains all of these types. Mutually exclusive with `version_or`." }, { "name": "version_or[]", "in": "query", "schema": { "type": "array", "items": { "type": "string", "enum": [ "original", "re_release", "edit", "remix", "acoustic", "alt_ver", "physical_ver", "cover", "live", "feat_or_collab", "dub", "remaster", "bonus", "arrangement", "commentary", "lofi", "component", "karaoke", "compilation_rerelease", "explicit", "clean", "other" ] }, "description": "Return tracks whose cluster contains at least one of these types. Mutually exclusive with `version_and`." }, "required": false, "description": "Return tracks whose cluster contains at least one of these types. Mutually exclusive with `version_and`." }, { "name": "version_not[]", "in": "query", "schema": { "type": "array", "items": { "type": "string", "enum": [ "original", "re_release", "edit", "remix", "acoustic", "alt_ver", "physical_ver", "cover", "live", "feat_or_collab", "dub", "remaster", "bonus", "arrangement", "commentary", "lofi", "component", "karaoke", "compilation_rerelease", "explicit", "clean", "other" ] }, "description": "Exclude tracks whose cluster contains any of these types." }, "required": false, "description": "Exclude tracks whose cluster contains any of these types." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "array", "items": { "type": "object", "properties": {} } }, "offset": { "type": [ "integer", "null" ], "description": "Echo of the requested `offset` for pagination." }, "total": { "type": [ "integer", "null" ], "minimum": 0, "description": "Total number of tracks matching the filters across all pages." } }, "required": [ "obj" ] }, "examples": { "default": { "value": { "obj": [ { "cm_track": 149018957, "album": [ { "id": 45564975, "label": "Republic Records", "name": "Golden (from the Netflix film KPop Demon Hunters)", "release_date": "2025-06-19", "upc": "602478712197" } ], "artist": [ { "id": 13915334, "name": "HUNTR/X" }, { "id": 13937011, "name": "EJAE" } ], "explicit": false, "genre": [ "pop", "k-pop", "pop r&b" ], "image_url": "https://i.scdn.co/image/ab67616d0000b2734dcb6c5df15cf74596ab25a4", "isrc": "QZ8BZ2513510", "name": "Golden", "score": 99.82791623840855, "songwriter": [], "latest": { "airplay_streams": 237386, "spotify_playlist_count": 72180, "spotify_plays": 984460584, "tiktok_posts": 1200000 }, "weekly_diff": { "spotify_plays": 15000000 }, "monthly_diff": { "spotify_plays": 60000000 } } ], "offset": 0, "total": 1 } } } } } } } } }, "/api/genre": { "get": { "summary": "List Chartmetric Genres (legacy path)", "tags": [ "Genre" ], "operationId": "listGenresLegacy", "description": "List Chartmetric genres. Accepts `isLegacy` to switch between `genre_v2` (default) and the legacy `genre` taxonomy. Equivalent response shape to `GET /api/genres`.", "parameters": [ { "name": "isLegacy", "in": "query", "schema": { "type": "boolean", "description": "When true, returns the legacy `genre` taxonomy; when false (default), returns the modern `genre_v2` taxonomy.", "default": false }, "required": false, "description": "When true, returns the legacy `genre` taxonomy; when false (default), returns the modern `genre_v2` taxonomy." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Chartmetric genre ID." }, "name": { "type": "string", "description": "Genre name (e.g. `pop`, `hip-hop/rap`)." } }, "required": [ "id", "name" ] } } }, "required": [ "obj" ], "additionalProperties": false }, "examples": { "default": { "value": { "obj": [ { "id": 501120, "name": "pop" }, { "id": 501121, "name": "hip-hop/rap" } ] } } } } } } } } }, "/api/festival/list": { "get": { "summary": "Festival List", "tags": [ "Festival" ], "operationId": "listFestivals", "description": "Get Chartmetric's Festival List. Supports filtering by country codes, genre IDs, event-size categories, and name search. Sort by `festivalName`, `rank`, `startDate` (default), `numberOfDays`, `eventSize`, `score`, or `totalEditions`.", "parameters": [ { "name": "code2s[]", "in": "query", "schema": { "type": "array", "items": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB').", "title": "code2" }, "description": "Filter to festivals held in these countries (ISO 3166-1 alpha-2 codes, e.g. ['US', 'GB'])." }, "required": false, "description": "Filter to festivals held in these countries (ISO 3166-1 alpha-2 codes, e.g. ['US', 'GB'])." }, { "name": "genreIds[]", "in": "query", "schema": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "description": "Filter to festivals matching any of these Chartmetric genre IDs." }, "required": false, "description": "Filter to festivals matching any of these Chartmetric genre IDs." }, { "name": "sortColumn", "in": "query", "schema": { "type": "string", "enum": [ "rank", "score", "festivalName", "startDate", "numberOfDays", "eventSize", "totalEditions" ], "description": "Column used to sort the festival list. One of `rank`, `score`, `festivalName`, `startDate`, `numberOfDays`, `eventSize`, `totalEditions`. Defaults to `startDate`.", "default": "startDate" }, "required": false, "description": "Column used to sort the festival list. One of `rank`, `score`, `festivalName`, `startDate`, `numberOfDays`, `eventSize`, `totalEditions`. Defaults to `startDate`." }, { "name": "sortOrderDesc", "in": "query", "schema": { "type": "boolean", "description": "If true, sort `sortColumn` in descending order. Defaults to false.", "default": false }, "required": false, "description": "If true, sort `sortColumn` in descending order. Defaults to false." }, { "name": "nameSearch", "in": "query", "schema": { "type": "string", "maxLength": 100, "description": "Case-insensitive substring filter on festival name." }, "required": false, "description": "Case-insensitive substring filter on festival name." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "description": "Maximum number of items to return per request.", "default": 10 }, "required": false, "description": "Maximum number of items to return per request." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 100000, "description": "Number of items to skip from the start of the result set; bounded by the public API offset limit." }, "required": false, "description": "Number of items to skip from the start of the result set; bounded by the public API offset limit." }, { "name": "eventSizes[]", "in": "query", "schema": { "type": "array", "items": { "type": "string", "enum": [ "small", "medium", "large", "mega" ] }, "description": "Filter by festival size category. One of `small`, `medium`, `large`, `mega`." }, "required": false, "description": "Filter by festival size category. One of `small`, `medium`, `large`, `mega`." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Chartmetric event ID for the festival." }, "name": { "type": [ "string", "null" ], "description": "Festival name." }, "date": { "type": [ "string", "null" ], "description": "Festival start date in `YYYY-MM-DD HH:MM:SS.MMM` format." }, "numberOfDays": { "type": [ "integer", "null" ], "description": "Number of days the festival lasts." }, "city": { "type": [ "string", "null" ], "description": "City where the festival is held." }, "country": { "type": [ "string", "null" ], "description": "Country where the festival is held (ISO 3166-1 alpha-2 code)." }, "performersCount": { "type": [ "integer", "null" ], "description": "Number of artists associated with the festival lineup." }, "popularityRank": { "type": [ "integer", "null" ], "description": "Festival popularity rank (lower is more popular)." }, "eventSize": { "type": "string", "description": "Size category of the festival (e.g. `Mega (60K+)`, `Large`, `Medium`, `Small`)." }, "topGenres": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric genre ID." }, "name": { "type": "string", "description": "Genre name." } }, "required": [ "id", "name" ] }, "description": "Top genres associated with the festival." }, "links": { "type": "object", "properties": { "jambase": { "type": [ "string", "null" ], "description": "JamBase festival page URL, when available." }, "songkick": { "type": [ "string", "null" ], "description": "Songkick festival page URL, when available." }, "seatgeek": { "type": [ "string", "null" ], "description": "SeatGeek festival page URL, when available." } }, "description": "Links to external pages about the festival." } }, "required": [ "id", "name", "date", "numberOfDays", "city", "country", "performersCount", "popularityRank", "eventSize", "topGenres", "links" ] } } }, "required": [ "obj" ], "additionalProperties": false }, "examples": { "default": { "value": { "obj": [ { "id": 642168, "name": "Rock Werchter", "date": "2025-07-03 00:00:00.000", "numberOfDays": 3, "city": "Werchter", "country": "BE", "performersCount": 89, "popularityRank": 21, "eventSize": "Mega (60K+)", "topGenres": [ { "id": 501120, "name": "pop" }, { "id": 501122, "name": "rock" }, { "id": 501124, "name": "electronic" } ], "links": { "jambase": "https://www.jambase.com/festival/rock-werchter-2025", "songkick": null, "seatgeek": null } } ] } } } } } } } } }, "/api/event/venue/{id}": { "get": { "summary": "List Events for a Venue", "tags": [ "Event" ], "operationId": "listEventsByVenue", "description": "List events taking place at a venue, with basic venue information and per-event artist lineups. Note: `venueInfo` is returned as an array of venue records, not a single object.", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "string", "description": "Chartmetric venue ID.", "title": "venue ID" }, "required": true, "description": "Chartmetric venue ID.", "examples": { "default": { "value": "2762" } } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum number of events to return. Defaults to 20, max 100.", "default": 20 }, "required": false, "description": "Maximum number of events to return. Defaults to 20, max 100." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." }, "required": false, "description": "Number of items to skip from the start of the result set; pair with `limit` to paginate." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "object", "properties": { "venueInfo": { "type": "array", "items": { "type": "object", "properties": { "doc_id": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "description": "Chartmetric venue ID." }, "name": { "type": [ "string", "null" ], "description": "Venue name." }, "lat": { "type": [ "number", "null" ], "format": "float", "description": "Venue latitude in decimal degrees (WGS84)." }, "lng": { "type": [ "number", "null" ], "format": "float", "description": "Venue longitude in decimal degrees (WGS84)." }, "cm_location": { "type": [ "integer", "null" ], "description": "Chartmetric location ID linking the venue to a city/region." }, "code2": { "type": [ "string", "null" ], "description": "Country of the venue (ISO 3166-1 alpha-2 code)." }, "image_url": { "type": [ "string", "null" ], "description": "Venue image URL." }, "city_id": { "type": [ "integer", "null" ], "description": "Chartmetric city ID where the venue is located." }, "capacity": { "type": [ "integer", "null" ], "description": "Approximate audience capacity of the venue." }, "city_name": { "type": [ "string", "null" ], "description": "City name where the venue is located." }, "venue_url": { "type": [ "string", "null" ], "description": "Venue's official website URL." } } }, "description": "Venue records (returned as an array even for a single venue)." }, "events": { "type": "array", "items": { "type": "object", "properties": { "event_id": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric event ID." }, "event_name": { "type": [ "string", "null" ], "description": "Event name." }, "event_image_url": { "type": [ "string", "null" ], "description": "Event image URL." }, "start_date": { "anyOf": [ { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Event start date in ISO 8601 format." }, "end_date": { "anyOf": [ { "type": "string" }, { "type": "string", "format": "date-time" } ], "nullable": true, "description": "Currently always an empty string due to a latent reducer bug." }, "artists": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ], "description": "Chartmetric artist ID." }, "name": { "type": [ "string", "null" ], "description": "Artist name." }, "is_headliner": { "type": [ "boolean", "null" ], "description": "True if the artist headlined the event, false if they performed but did not headline, null if headliner status is unknown." } } }, "description": "Artists performing at the event." } }, "required": [ "event_id", "artists" ] }, "description": "Events at the venue, ordered by `start_date` (newest first) and paginated by `limit`/`offset`." } }, "required": [ "venueInfo", "events" ] } }, "additionalProperties": false }, "examples": { "default": { "value": { "obj": { "venueInfo": [ { "doc_id": 1, "name": "Greek Theatre", "lat": 37.8726, "lng": -122.254, "cm_location": null, "code2": "US", "image_url": "https://www.jambase.com/wp-content/uploads/2015/06/greek-1480x832.jpg", "city_id": 6312, "capacity": 8500, "city_name": "Berkeley", "venue_url": "https://thegreekberkeley.com/" } ], "events": [ { "event_id": 8553348, "event_name": "Modest Mouse at Greek Theatre", "event_image_url": "https://www.jambase.com/wp-content/uploads/2019/03/modest-mouse-2019-press-1480x832.jpg", "start_date": "2016-07-28T00:00:00.000Z", "end_date": "", "artists": [ { "id": 20, "name": "Modest Mouse", "is_headliner": null } ] } ] } } } } } } } } } }, "/api/SNS/deepSocial/cm_artist/{id}/instagram": { "get": { "summary": "Get Artist Instagram Top Posts and Reels", "tags": [ "SNS" ], "operationId": "getArtistInstagramTopPostsAndReels", "description": "Returns the artist's top 10 Instagram posts and top 10 Instagram reels. The handler passes through the `user_profile.top_posts` and `user_profile.top_reels` arrays from the deep-social pipeline; either array may be empty when no data is available.", "parameters": [ { "name": "id", "in": "path", "schema": { "type": "integer", "minimum": 2, "maximum": 2147483647, "not": { "enum": [ 1 ] }, "description": "Chartmetric artist ID. Note: id=1 ('Various Artists') is rejected." }, "required": true, "description": "Chartmetric artist ID. Note: id=1 ('Various Artists') is rejected.", "examples": { "default": { "value": 2 } } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "object", "properties": { "top_posts": { "type": "array", "items": { "type": "object", "properties": { "user_id": { "type": [ "string", "null" ], "description": "Instagram numeric user ID of the posting account." }, "username": { "type": [ "string", "null" ], "description": "Instagram handle of the posting account." }, "user_picture": { "type": [ "string", "null" ], "description": "URL of the posting account's profile picture." }, "user_url": { "type": [ "string", "null" ], "description": "URL of the posting account's Instagram profile." }, "type": { "type": [ "string", "null" ], "description": "Post media type, e.g. 'photo' or 'video'." }, "post_id": { "type": [ "string", "null" ], "description": "Instagram post identifier." }, "created": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp of when the post was created." }, "text": { "type": [ "string", "null" ], "description": "Caption or text content of the post." }, "image": { "type": [ "string", "null" ], "description": "URL of the post image or, for videos, the video thumbnail." }, "thumbnail": { "type": [ "string", "null" ], "description": "URL of the post thumbnail image." }, "link": { "type": [ "string", "null" ], "description": "Direct URL to the post on Instagram." }, "mentions": { "type": "array", "items": { "type": "string" }, "description": "Instagram handles mentioned in the caption." }, "stat": { "type": "object", "properties": { "likes_count_enabled": { "type": "boolean", "description": "Whether the like count is publicly visible on Instagram; when `false`, `likes` may be hidden or zeroed." }, "likes": { "type": [ "integer", "null" ], "description": "Total number of likes on the post." }, "comments": { "type": [ "integer", "null" ], "description": "Total number of comments on the post." }, "shares": { "type": [ "integer", "null" ], "description": "Total number of shares on the post." }, "plays": { "type": [ "integer", "null" ], "description": "Total number of plays; populated for reels only." } }, "description": "Engagement statistics for the post." } } }, "description": "Up to 10 of the artist's top Instagram posts, ranked by engagement; empty when no data is available." }, "top_reels": { "type": "array", "items": { "type": "object", "properties": { "user_id": { "type": [ "string", "null" ], "description": "Instagram numeric user ID of the posting account." }, "username": { "type": [ "string", "null" ], "description": "Instagram handle of the posting account." }, "user_picture": { "type": [ "string", "null" ], "description": "URL of the posting account's profile picture." }, "user_url": { "type": [ "string", "null" ], "description": "URL of the posting account's Instagram profile." }, "type": { "type": [ "string", "null" ], "description": "Post media type, e.g. 'photo' or 'video'." }, "post_id": { "type": [ "string", "null" ], "description": "Instagram post identifier." }, "created": { "type": [ "string", "null" ], "description": "ISO 8601 timestamp of when the post was created." }, "text": { "type": [ "string", "null" ], "description": "Caption or text content of the post." }, "image": { "type": [ "string", "null" ], "description": "URL of the post image or, for videos, the video thumbnail." }, "thumbnail": { "type": [ "string", "null" ], "description": "URL of the post thumbnail image." }, "link": { "type": [ "string", "null" ], "description": "Direct URL to the post on Instagram." }, "mentions": { "type": "array", "items": { "type": "string" }, "description": "Instagram handles mentioned in the caption." }, "stat": { "type": "object", "properties": { "likes_count_enabled": { "type": "boolean", "description": "Whether the like count is publicly visible on Instagram; when `false`, `likes` may be hidden or zeroed." }, "likes": { "type": [ "integer", "null" ], "description": "Total number of likes on the post." }, "comments": { "type": [ "integer", "null" ], "description": "Total number of comments on the post." }, "shares": { "type": [ "integer", "null" ], "description": "Total number of shares on the post." }, "plays": { "type": [ "integer", "null" ], "description": "Total number of plays; populated for reels only." } }, "description": "Engagement statistics for the post." } } }, "description": "Up to 10 of the artist's top Instagram reels, ranked by engagement; empty when no data is available." } }, "required": [ "top_posts", "top_reels" ] } }, "required": [ "obj" ], "additionalProperties": false }, "examples": { "default": { "value": { "obj": { "top_posts": [ { "user_id": "1707509864", "username": "honeymoon", "user_picture": "https://example.com/user_picture.jpg", "user_url": "https://www.instagram.com/honeymoon", "type": "photo", "post_id": "3730445037202445518_1707509864", "created": "2025-09-26T21:55:24.000+00:00", "image": "https://example.com/post_image.jpg", "thumbnail": "https://example.com/post_thumbnail.jpg", "link": "https://www.instagram.com/p/DPFM_8gkhTO/", "mentions": [ "jeremy.dufrene", "ralphlauren", "tiffanyandco" ], "stat": { "likes_count_enabled": true, "likes": 6717673, "comments": 40955, "shares": 301160 } } ], "top_reels": [ { "user_id": "1707509864", "username": "honeymoon", "user_picture": "https://example.com/user_picture.jpg", "user_url": "https://www.instagram.com/honeymoon", "type": "video", "post_id": "3394225214193878190_49509959", "created": "2024-06-20T00:29:37.000+00:00", "text": "Tough", "image": "https://example.com/reel_image.jpg", "thumbnail": "https://example.com/reel_thumbnail.jpg", "link": "https://www.instagram.com/p/C8atdlTs0Su/", "stat": { "likes_count_enabled": true, "likes": 3021396, "comments": 20994, "plays": 46374448 } } ] } } } } } } } } } }, "/api/venue": { "get": { "summary": "List Venues", "tags": [ "Venue" ], "operationId": "listVenues", "description": "List Chartmetric venues. Supports filtering by country (`code2`), Chartmetric city (`cityId`), venue type (`venueType`), venue name (`search`), and capacity range (`minCapacity`/`maxCapacity`), and sorting by `name` (default), `capacity`, or `latestShowDate`. Each venue includes its most recent show and the most popular artist on record to have performed there. By default the \"latest show\" only considers shows that have already happened; pass `includeFutureShows=true` to allow an upcoming show to be picked instead.", "parameters": [ { "name": "code2", "in": "query", "schema": { "type": "string", "minLength": 2, "maxLength": 2, "description": "Filter to venues in this country (ISO 3166-1 alpha-2 code, e.g. 'US')." }, "required": false, "description": "Filter to venues in this country (ISO 3166-1 alpha-2 code, e.g. 'US')." }, { "name": "cityId", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Filter to venues in this Chartmetric city." }, "required": false, "description": "Filter to venues in this Chartmetric city." }, { "name": "minCapacity", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Filter to venues with a capacity greater than or equal to this value." }, "required": false, "description": "Filter to venues with a capacity greater than or equal to this value." }, { "name": "maxCapacity", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Filter to venues with a capacity less than or equal to this value." }, "required": false, "description": "Filter to venues with a capacity less than or equal to this value." }, { "name": "venueType", "in": "query", "schema": { "type": "string", "enum": [ "stadium", "arena", "amphitheater", "festival", "theater", "concert_hall", "club" ], "description": "Filter to venues of this type. One of `stadium`, `arena`, `amphitheater`, `festival`, `theater`, `concert_hall`, `club`." }, "required": false, "description": "Filter to venues of this type. One of `stadium`, `arena`, `amphitheater`, `festival`, `theater`, `concert_hall`, `club`." }, { "name": "search", "in": "query", "schema": { "type": "string", "maxLength": 200, "description": "Filter to venues whose name contains this value (case-insensitive)." }, "required": false, "description": "Filter to venues whose name contains this value (case-insensitive)." }, { "name": "sortColumn", "in": "query", "schema": { "type": "string", "enum": [ "name", "capacity", "latestShowDate" ], "description": "Column used to sort the venue list. One of `name`, `capacity`, `latestShowDate`. Defaults to `name`.", "default": "name" }, "required": false, "description": "Column used to sort the venue list. One of `name`, `capacity`, `latestShowDate`. Defaults to `name`." }, { "name": "sortOrderDesc", "in": "query", "schema": { "type": "boolean", "description": "If true, sort `sortColumn` in descending order. Defaults to false.", "default": false }, "required": false, "description": "If true, sort `sortColumn` in descending order. Defaults to false." }, { "name": "includeFutureShows", "in": "query", "schema": { "type": "boolean", "description": "If true, a venue’s “latest show” may be an upcoming (future-dated) show. Defaults to false, which only considers shows that have already happened.", "default": false }, "required": false, "description": "If true, a venue’s “latest show” may be an upcoming (future-dated) show. Defaults to false, which only considers shows that have already happened." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Maximum number of venues to return. Defaults to 20, max 100.", "default": 20 }, "required": false, "description": "Maximum number of venues to return. Defaults to 20, max 100." }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 100000, "description": "Number of items to skip from the start of the result set; bounded by the public API offset limit." }, "required": false, "description": "Number of items to skip from the start of the result set; bounded by the public API offset limit." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "obj": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric venue ID." }, "name": { "type": [ "string", "null" ], "description": "Venue name." }, "image_url": { "type": [ "string", "null" ], "description": "Venue image URL." }, "city": { "type": [ "string", "null" ], "description": "City where the venue is located." }, "city_id": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647, "description": "Chartmetric city ID where the venue is located, or `null` if unknown." }, "country": { "type": [ "string", "null" ], "description": "Country where the venue is located (ISO 3166-1 alpha-2 code)." }, "lat": { "type": [ "number", "null" ], "format": "float", "description": "Venue latitude in decimal degrees (WGS84)." }, "lng": { "type": [ "number", "null" ], "format": "float", "description": "Venue longitude in decimal degrees (WGS84)." }, "capacity": { "type": [ "integer", "null" ], "description": "Approximate audience capacity of the venue." }, "venue_type": { "type": [ "string", "null" ], "enum": [ "stadium", "arena", "amphitheater", "festival", "theater", "concert_hall", "club" ], "description": "Coarse venue type derived from the venue name — one of `stadium`, `arena`, `amphitheater`, `festival`, `theater`, `concert_hall`, `club` — or `null` when unclassified." }, "latest_show": { "type": [ "object", "null" ], "properties": { "date": { "type": [ "string", "null" ], "format": "date-time", "description": "Start date of the venue’s most recent show." }, "title": { "type": [ "string", "null" ], "description": "Name of the venue’s most recent show." } }, "required": [ "date", "title" ], "description": "The venue’s most recent show, or `null` if it has none on record." }, "biggest_artist": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric artist ID." }, "name": { "type": "string", "description": "Artist name." }, "image_url": { "type": [ "string", "null" ], "description": "Artist image URL, or `null` if none is on record." } }, "required": [ "id", "name", "image_url" ], "description": "The most popular artist (by Chartmetric artist rank) to have performed at this venue, or `null` if none is on record." }, "show_count": { "type": "integer", "description": "Days with a show at the venue on record (duplicate records merged)." }, "show_trend": { "type": "array", "items": { "type": "integer" }, "description": "Days with a show per month over the last 24 months, oldest first, the current month last." }, "top_artists": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": 0, "maximum": 2147483647, "description": "Chartmetric artist ID." }, "name": { "type": "string", "description": "Artist name." }, "image_url": { "type": [ "string", "null" ], "description": "Artist image URL, or `null` if none is on record." } }, "required": [ "id", "name", "image_url" ] }, "description": "Up to three of the most popular artists (by Chartmetric artist rank) to have performed at this venue, most popular first; `biggest_artist` is the first of them." } }, "required": [ "id", "name", "image_url", "city", "city_id", "country", "lat", "lng", "capacity", "venue_type", "latest_show", "biggest_artist", "show_count", "show_trend", "top_artists" ] }, "description": "Page of matching venues." }, "total": { "type": [ "integer", "null" ], "description": "Total number of venues matching the filters, across all pages." } }, "required": [ "data", "total" ] } }, "additionalProperties": false }, "examples": { "default": { "value": { "obj": { "data": [ { "id": 1, "name": "Greek Theatre", "image_url": "https://www.jambase.com/wp-content/uploads/2015/06/greek-1480x832.jpg", "city": "Berkeley", "city_id": 5391959, "country": "US", "lat": 37.8726, "lng": -122.254, "capacity": 8500, "venue_type": "theater", "latest_show": { "date": "2016-07-28T00:00:00.000Z", "title": "Modest Mouse at Greek Theatre" }, "biggest_artist": { "id": 20, "name": "Modest Mouse", "image_url": null }, "show_count": 412, "show_trend": [ 3, 2, 4, 5, 6, 4, 2, 1, 0, 2, 3, 5, 4, 3, 5, 6, 7, 5, 3, 2, 1, 2, 4, 3 ], "top_artists": [ { "id": 20, "name": "Modest Mouse", "image_url": null }, { "id": 1021, "name": "Bon Iver", "image_url": null } ] } ], "total": 1 } } } } } } } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT access token obtained from /api/token" } } }, "security": [ { "BearerAuth": [] } ], "x-ext-urls": {} }