# Chartmetric Developer API - **OpenAPI Version:** `3.1.1` - **API Version:** `0.0.1` Public API documentation for the Chartmetric Developer API ## Servers - **URL:** `https://api.chartmetric.com` - **Description:** Production ## Operations ### Create API Access Token - **Method:** `POST` - **Path:** `/api/token` - **Tags:** Token Exchange a refresh token for a short-lived JWT access token used to authorize Developer API requests. #### Request Body ##### Content-Type: application/json - **`refreshtoken` (required)** `string` **Example:** ```json { "refreshtoken": "" } ``` #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`expires_in` (required)** `integer` — Lifetime in seconds - **`refresh_token` (required)** `string` - **`scope` (required)** `string` - **`token` (required)** `string` — JWT access token **Example:** ```json { "token": "", "expires_in": 1, "refresh_token": "", "scope": "" } ``` ### Chartmetric Search - **Method:** `GET` - **Path:** `/api/search` - **Tags:** Search 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. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj` (required)** `object` - **`albums` (required)** `array` **Items:** - **`id` (required)** `integer` - **`name` (required)** `string` - **`image_url`** `string | null` - **`label`** `string | null` - **`artists` (required)** `array` **Items:** - **`id` (required)** `integer` - **`name` (required)** `string` - **`cm_artist_score`** `number | null`, format: `float` - **`image_url`** `string | null` - **`isni`** `string | null` - **`sp_followers`** `integer | null` - **`sp_monthly_listeners`** `integer | null` - **`cities` (required)** `array` **Items:** - **`id` (required)** `integer` - **`name` (required)** `string` - **`code2`** `string | null` - **`country`** `string | null` - **`name_ascii`** `string | null` - **`population`** `number | null`, format: `float` - **`province`** `string | null` - **`trigger_city`** `boolean` - **`curators` (required)** `object` - **`amazon` (required)** `array` **Items:** - **`applemusic` (required)** `array` **Items:** - **`id` (required)** `integer` - **`image_url`** `string | null` - **`name`** `string | null` - **`deezer` (required)** `array` **Items:** - **`id` (required)** `object` - **`image_url`** `string | null` - **`name`** `string | null` - **`spotify` (required)** `array` **Items:** - **`id` (required)** `integer` - **`image_url`** `string | null` - **`name`** `string | null` - **`youtube` (required)** `array` **Items:** - **`festivals` (required)** `array` **Items:** - **`genres` (required)** `array` **Items:** - **`labels` (required)** `array` **Items:** - **`playlists` (required)** `object` - **`amazon` (required)** `array` **Items:** - **`id` (required)** `object` - **`name` (required)** `string` - **`image_url`** `string | null` - **`owner_name`** `string | null` - **`applemusic` (required)** `array` **Items:** - **`id` (required)** `integer` - **`name` (required)** `string` - **`image_url`** `string | null` - **`owner_name`** `string | null` - **`deezer` (required)** `array` **Items:** - **`id` (required)** `object` - **`name` (required)** `string` - **`image_url`** `string | null` - **`owner_name`** `string | null` - **`soundcloud` (required)** `array` **Items:** - **`spotify` (required)** `array` **Items:** - **`id` (required)** `integer` - **`name` (required)** `string` - **`image_url`** `string | null` - **`owner_name`** `string | null` - **`youtube` (required)** `array` **Items:** - **`id` (required)** `string` - **`name` (required)** `string` - **`image_url`** `string | null` - **`songwriters` (required)** `array` **Items:** - **`doc_id` (required)** `integer` - **`artistName`** `string | null` - **`image_url`** `string | null` - **`name`** `string | null` - **`stations` (required)** `array` **Items:** - **`id` (required)** `integer` - **`name` (required)** `string` - **`country`** `string | null` - **`genre`** `string | null` - **`image_url`** `string | null` - **`station_city`** `string | null` - **`tracks` (required)** `array` **Items:** - **`artist_names` (required)** `array` **Items:** `string` - **`id` (required)** `object` - **`name` (required)** `string` - **`image_url`** `string | null` - **`isrc`** `string | null` - **`countries`** `array` **Items:** **Example:** ```json { "obj": { "artists": [ { "id": 0, "name": "", "image_url": null, "isni": null, "sp_followers": null, "sp_monthly_listeners": null, "cm_artist_score": null } ], "playlists": { "spotify": [ { "id": 0, "name": "", "image_url": null, "owner_name": null } ], "applemusic": [ { "id": 0, "name": "", "image_url": null, "owner_name": null } ], "deezer": [ { "id": "", "name": "", "image_url": null, "owner_name": null } ], "amazon": [ { "id": "", "name": "", "image_url": null, "owner_name": null } ], "youtube": [ { "id": "", "name": "", "image_url": null } ], "soundcloud": [] }, "tracks": [ { "id": "", "name": "", "image_url": null, "isrc": null, "artist_names": [ "" ] } ], "curators": { "spotify": [ { "id": 0, "name": null, "image_url": null } ], "applemusic": [ { "id": 0, "name": null, "image_url": null } ], "deezer": [ { "id": "", "name": null, "image_url": null } ], "amazon": [], "youtube": [] }, "albums": [ { "id": 0, "name": "", "image_url": null, "label": null } ], "stations": [ { "id": 0, "name": "", "genre": null, "image_url": null, "station_city": null, "country": null } ], "labels": [], "cities": [ { "id": 0, "name": "", "name_ascii": null, "population": null, "country": null, "code2": null, "province": null, "trigger_city": true } ], "countries": [], "songwriters": [ { "name": null, "doc_id": 0, "artistName": null, "image_url": null } ], "genres": [], "festivals": [] } } ``` ### Chartmetric Social Search - **Method:** `GET` - **Path:** `/api/search/social` - **Tags:** Search 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. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj` (required)** `array` **Items:** - **`id` (required)** `object` - **`image_url`** `string | null` - **`name`** `string | null` - **`type`** `string | null` **Example:** ```json { "obj": [ { "id": "", "type": null, "name": null, "image_url": null } ] } ``` ### List Chartmetric Genres - **Method:** `GET` - **Path:** `/api/genres` - **Tags:** Genre List Chartmetric genres, optionally filtered by `name`. Pass `isLegacy=true` to receive the legacy `genre` taxonomy instead of `genre_v2`. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj` (required)** `array` **Items:** - **`id` (required)** `integer` - **`name` (required)** `string` **Example:** ```json { "obj": [ { "id": 1, "name": "" } ] } ``` ### Get Genre by ID - **Method:** `GET` - **Path:** `/api/genres/{id}` - **Tags:** Genre Fetch a single Chartmetric genre by its ID. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj`** `object | null` - **`id` (required)** `integer` - **`name` (required)** `string` - **`source` (required)** `string` - **`type` (required)** `string`, possible values: `"genre", "genre_v2"` **Example:** ```json { "obj": { "id": 1, "name": "", "type": "genre", "source": "" } } ``` ### List Cities by Country - **Method:** `GET` - **Path:** `/api/cities` - **Tags:** City List cities within a country (ISO 3166-1 alpha-2 `country_code`). Optionally narrow to a single city by `city_id`. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj` (required)** `array` **Items:** - **`city_id` (required)** `integer` - **`city_name` (required)** `string` - **`country`** `string | null` - **`image_url`** `string | null` - **`iso3`** `string | null` - **`latitude`** `number | null`, format: `float` - **`locality`** `string | null` - **`longitude`** `number | null`, format: `float` - **`population`** `integer | null` - **`province`** `string | null` **Example:** ```json { "obj": [ { "city_id": 1, "city_name": "", "latitude": null, "longitude": null, "population": null, "province": null, "locality": null, "country": null, "image_url": null, "iso3": null } ] } ``` ### Album Charts - **Method:** `GET` - **Path:** `/api/album/{id}/{type}/charts` - **Tags:** Album Chart history for an album on a platform (`applemusic`, `itunes`, or `amazon`). Date range accepts up to 365 days between `since` and `until`. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj`** `object` - **`length` (required)** `integer` - **`data`** `array | null` **Example:** ```json { "obj": { "data": [ { "itunes_album_id": null, "rank": null, "added_at": null, "code2": null, "genre": null, "gnp": null, "pre_rank": null, "peak_rank": null, "peak_date": null, "id": null, "name": null, "release_date": null, "copyright": null, "num_track": null, "upc": null, "description": null, "is_single": null, "artwork_url": null, "label": null, "genres": null, "created_at": null, "modified_at": null, "cm_album": null, "storefronts": [ "" ], "itunes_album_ids": [ "" ], "artists": [ { "itunes_artist_id": null, "name": null, "cm_artist": null } ] } ], "length": 0 } } ``` ### Get Album IDs - **Method:** `GET` - **Path:** `/api/album/{type}/{id}/get-ids` - **Tags:** Album 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. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj` (required)** `array` **Items:** - **`cm_album` (required)** `integer` - **`album_name`** `string | null` - **`amazon_album_id`** `string | null` - **`deezer_album_id`** `string | null` - **`itunes_album_id`** `string | null` - **`spotify_album_id`** `string | null` - **`upc`** `string | null` **Example:** ```json { "obj": [ { "cm_album": 0, "album_name": null, "upc": null, "spotify_album_id": null, "itunes_album_id": null, "deezer_album_id": null, "amazon_album_id": null } ] } ``` ### Album Metadata - **Method:** `GET` - **Path:** `/api/album/{id}` - **Tags:** Album Album metadata by Chartmetric ID. Cached daily. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj`** `object` - **`cm_album` (required)** `integer` - **`artists`** `array | null` - **`cm_label`** `integer | null` - **`cm_statistics`** `object | null` - **`num_sp_editorial_playlists`** `integer | null` - **`num_sp_playlists`** `integer | null` - **`sp_editorial_playlist_total_reach`** `integer | null` - **`sp_playlist_total_reach`** `integer | null` - **`sp_popularity`** `integer | null` - **`created_at`** `string | null`, format: `date-time` - **`deezer_album_ids`** `array | null` - **`description`** `string | null` - **`id`** `integer | null` - **`image_url`** `string | null` - **`itunes_album_ids`** `array | null` - **`label`** `string | null` - **`modified_at`** `string | null`, format: `date-time` - **`name`** `string | null` - **`num_track`** `object` - **`release_date`** `string | null` - **`spotify_album_ids`** `array | null` - **`spotify_popularity`** `integer | null` - **`upc`** `string | null` **Example:** ```json { "obj": { "id": null, "upc": null, "name": null, "image_url": null, "release_date": null, "label": null, "spotify_popularity": null, "cm_label": null, "description": null, "created_at": null, "modified_at": null, "cm_album": 0, "num_track": "", "spotify_album_ids": [ "" ], "itunes_album_ids": [ "" ], "deezer_album_ids": [ "" ], "artists": [ { "cm_artist": 0, "name": null, "image_url": null } ], "cm_statistics": { "sp_popularity": null, "num_sp_editorial_playlists": null, "num_sp_playlists": null, "sp_playlist_total_reach": null, "sp_editorial_playlist_total_reach": null } } } ``` ### Album Tracks - **Method:** `GET` - **Path:** `/api/album/{id}/tracks` - **Tags:** Album 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 and will be deprecated. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj` (required)** `array` **Items:** - **`id` (required)** `integer` - **`album_ids`** `array | null` - **`album_label`** `array | null` - **`album_names`** `array | null` - **`album_upc`** `array | null` - **`amazon_album_ids`** `array | null` - **`amazon_track_ids`** `array | null` - **`artist_covers`** `array | null` - **`artist_images`** `array | null` - **`artist_names`** `array | null` - **`cm_artist`** `array | null` - **`cm_artists`** `array | null` - **`cm_statistics`** `object | null` - **`cm_track`** `integer | null` - **`de_playlist_total_reach`** `object` - **`genius_page_views`** `number | null`, format: `float` - **`num_am_editorial_playlists`** `number | null`, format: `float` - **`num_am_playlists`** `number | null`, format: `float` - **`num_az_editorial_playlists`** `number | null`, format: `float` - **`num_az_playlists`** `number | null`, format: `float` - **`num_de_editorial_playlists`** `number | null`, format: `float` - **`num_de_playlists`** `number | null`, format: `float` - **`num_sp_editorial_playlists`** `number | null`, format: `float` - **`num_sp_playlists`** `number | null`, format: `float` - **`num_tt_videos`** `integer | null` - **`num_yt_editorial_playlists`** `number | null`, format: `float` - **`num_yt_playlists`** `number | null`, format: `float` - **`shazam_counts`** `number | null`, format: `float` - **`sp_playlist_total_reach`** `object` - **`sp_popularity`** `integer | null` - **`tiktok_counts`** `number | null`, format: `float` - **`youtube_views`** `object` - **`yt_playlist_total_reach`** `object` - **`cm_track`** `integer | null` - **`code2s`** `array | null` - **`created_at`** `string | null`, format: `date-time` - **`deezer_album_ids`** `array | null` - **`deezer_duration`** `integer | null` - **`deezer_track_ids`** `array | null` - **`description`** `string | null` - **`image_url`** `string | null` - **`isrc`** `string | null` - **`itunes_album_ids`** `array | null` - **`itunes_track_ids`** `array | null` - **`modified_at`** `string | null`, format: `date-time` - **`name`** `string | null` - **`release_dates`** `array | null` - **`spotify_album_ids`** `array | null` - **`spotify_duration_ms`** `integer | null` - **`spotify_track_ids`** `array | null` - **`storefronts`** `array | null` - **`tags`** `string | null` **Example:** ```json { "obj": [ { "id": 0, "name": null, "image_url": null, "isrc": null, "description": null, "created_at": null, "modified_at": null, "tags": null, "cm_track": null, "cm_artist": [ 0 ], "artist_names": [ "" ], "code2s": [ null ], "artist_images": [ null ], "artist_covers": [ null ], "spotify_track_ids": [ "" ], "spotify_album_ids": [ "" ], "spotify_duration_ms": null, "itunes_track_ids": [ "" ], "itunes_album_ids": [ "" ], "storefronts": [ "" ], "deezer_track_ids": [ "" ], "deezer_album_ids": [ "" ], "deezer_duration": null, "amazon_track_ids": [ "" ], "amazon_album_ids": [ "" ], "album_ids": [ 0 ], "album_names": [ "" ], "album_upc": [ "" ], "album_label": [ "" ], "release_dates": [ "" ], "cm_artists": [ { "id": 0, "name": null, "code2": null, "image_url": null, "cover_url": null } ], "cm_statistics": { "num_sp_editorial_playlists": null, "num_sp_playlists": null, "sp_playlist_total_reach": 1, "num_am_editorial_playlists": null, "num_am_playlists": null, "num_de_editorial_playlists": null, "num_de_playlists": null, "de_playlist_total_reach": 1, "num_az_editorial_playlists": null, "num_az_playlists": null, "num_yt_editorial_playlists": null, "num_yt_playlists": null, "yt_playlist_total_reach": 1, "cm_track": null, "sp_popularity": null, "num_tt_videos": null, "genius_page_views": null, "shazam_counts": null, "tiktok_counts": null, "youtube_views": 1 } } ] } ``` ### Album Platform Stats - **Method:** `GET` - **Path:** `/api/album/{id}/{platform}/{stats}` - **Tags:** Album 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. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj` (required)** `array` **Items:** - **`timestp` (required)** `string`, format: `date-time` - **`value` (required)** `number`, format: `float` - **`daily_diff`** `number`, format: `float` - **`extrapolated`** `boolean` - **`flags`** `boolean` - **`interpolated`** `boolean` - **`monthly_diff`** `number`, format: `float` - **`monthly_diff_percent`** `number`, format: `float` - **`weekly_diff`** `number`, format: `float` - **`weekly_diff_percent`** `number`, format: `float` **Example:** ```json { "obj": [ { "value": 1, "timestp": "", "daily_diff": 1, "weekly_diff": 1, "monthly_diff": 1, "weekly_diff_percent": 1, "monthly_diff_percent": 1, "flags": true, "interpolated": true, "extrapolated": true } ] } ``` ### Album Playlists - **Method:** `GET` - **Path:** `/api/album/{id}/{platform}/{status}/playlists` - **Tags:** Album Playlists (`status=current` or `past`) featuring an album on a given streaming platform. Supports a large set of boolean platform-specific filters — see the apidoc for the matrix. Items pair a `playlist` object with the corresponding `track` metadata. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj` (required)** `array` **Items:** - **`playlist`** `object` - **`active_ratio`** `number | null`, format: `float` - **`added_at`** `object` - **`catalog`** `string | null` - **`code2`** `string | null` - **`description`** `string | null` - **`editorial`** `boolean | null` - **`fdiff_month`** `integer | null` - **`fdiff_week`** `integer | null` - **`followers`** `integer | null` - **`id`** `integer | null` - **`image_url`** `string | null` - **`last_updated`** `string | null`, format: `date-time` - **`name`** `string | null` - **`num_track`** `object` - **`owner_id`** `object` - **`owner_name`** `string | null` - **`period`** `integer | null` - **`personalized`** `boolean | null` - **`playlist_id`** `string | null` - **`position`** `integer | null` - **`sys_last_updated`** `string | null`, format: `date-time` - **`tags`** `array | null` - **`track_id`** `integer | null` - **`track`** `object` - **`album_ids`** `array | null` - **`album_label`** `array | null` - **`album_names`** `array | null` - **`album_upc`** `array | null` - **`artist_covers`** `array | null` - **`artist_images`** `array | null` - **`artist_names`** `array | null` - **`cm_artist`** `array | null` - **`cm_track`** `integer | null` - **`code2s`** `array | null` - **`id`** `integer | null` - **`image_url`** `string | null` - **`isrc`** `string | null` - **`name`** `string | null` - **`release_dates`** `array | null` - **`spotify_album_id`** `string | null` - **`spotify_album_ids`** `array | null` - **`spotify_artist_ids`** `array | null` - **`spotify_artist_names`** `array | null` - **`spotify_duration_ms`** `object` - **`spotify_popularity`** `integer | null` - **`spotify_track_ids`** `array | null` - **`track_genre`** `string | null` **Example:** ```json { "obj": [ { "playlist": { "playlist_id": null, "track_id": null, "position": null, "added_at": "", "period": null, "id": null, "name": null, "description": null, "image_url": null, "sys_last_updated": null, "last_updated": null, "personalized": null, "code2": null, "owner_name": null, "owner_id": "", "editorial": null, "tags": [ { "id": 0, "name": null } ], "followers": null, "num_track": "", "fdiff_week": null, "fdiff_month": null, "catalog": null, "active_ratio": null }, "track": { "id": null, "name": null, "isrc": null, "spotify_album_id": null, "image_url": null, "spotify_popularity": null, "cm_track": null, "spotify_artist_names": [ null ], "track_genre": null, "cm_artist": [ 0 ], "artist_names": [ null ], "code2s": [ null ], "artist_images": [ null ], "artist_covers": [ null ], "spotify_artist_ids": [ "" ], "spotify_track_ids": [ "" ], "spotify_album_ids": [ "" ], "spotify_duration_ms": 1, "album_ids": [ 0 ], "album_names": [ null ], "album_upc": [ null ], "album_label": [ null ], "release_dates": [ null ] } } ] } ``` ### A\&R Artists by Playlists - **Method:** `GET` - **Path:** `/api/artist/anr/by/playlists` - **Tags:** Artist 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. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj` (required)** `array` **Items:** - **`authenticity_risk`** `object` - **`cm_artist_rank`** `integer | null` - **`cm_artist_score`** `number | null`, format: `float` - **`code2`** `string | null` - **`deezer_fans`** `object` - **`followers`** `integer | null` - **`followers_diff_week`** `integer | null` - **`followers_diff_week_percent`** `number | null`, format: `float` - **`followers_total_reach`** `integer | null` - **`followers_total_reach_diff_week`** `integer | null` - **`followers_total_reach_diff_week_percent`** `number | null`, format: `float` - **`genres`** `array | null` - **`id`** `integer | null` - **`image_url`** `string | null` - **`listeners`** `integer | null` - **`listeners_diff_week`** `integer | null` - **`listeners_diff_week_percent`** `number | null`, format: `float` - **`name`** `string | null` - **`num_playlists`** `integer | null` - **`num_playlists_diff_week`** `integer | null` - **`num_playlists_diff_week_percent`** `number | null`, format: `float` - **`num_tracks`** `integer | null` - **`popularity`** `integer | null` - **`popularity_diff_week`** `integer | null` - **`popularity_diff_week_percent`** `number | null`, format: `float` - **`rank`** `object` - **`releases`** `array | null` - **`sp_followers`** `integer | null` - **`sp_monthly_listeners`** `integer | null` - **`sp_popularity`** `integer | null` - **`spotify_artist_ids`** `array | null` - **`tags`** `array | null` - **`timestp`** `object` **Example:** ```json { "obj": [ { "rank": 1, "id": null, "name": null, "image_url": null, "code2": null, "sp_followers": null, "sp_popularity": null, "sp_monthly_listeners": null, "deezer_fans": 1, "tags": [], "spotify_artist_ids": [ "" ], "cm_artist_rank": null, "cm_artist_score": null, "num_tracks": null, "num_playlists": null, "num_playlists_diff_week": null, "num_playlists_diff_week_percent": null, "followers_total_reach": null, "followers_total_reach_diff_week": null, "followers_total_reach_diff_week_percent": null, "popularity": null, "popularity_diff_week": null, "popularity_diff_week_percent": null, "followers": null, "followers_diff_week": null, "followers_diff_week_percent": null, "listeners": null, "listeners_diff_week": null, "listeners_diff_week_percent": null, "timestp": "", "releases": [ { "cm_album": null, "album_name": null, "release_date": "", "upc": null, "label": null, "image_url": null } ], "genres": [], "authenticity_risk": null } ] } ``` ### RIAA Certifications for Artist Albums - **Method:** `GET` - **Path:** `/api/artist/{id}/riaa` - **Tags:** Artist 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. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj`** `object` - **`riaa_awards` (required)** `array` **Items:** - **`album_title`** `string | null` - **`award`** `string | null` - **`award_id`** `integer | null` - **`certification_date`** `object` - **`cm_album`** `integer | null` - **`format`** `string | null` - **`image_url`** `string | null` - **`label`** `string | null` - **`upc`** `string | null` **Example:** ```json { "obj": { "riaa_awards": [ { "award_id": null, "cm_album": null, "upc": null, "certification_date": "", "award": null, "album_title": null, "format": null, "image_url": null, "label": null } ] } } ``` ### A\&R Artists by Social Index - **Method:** `GET` - **Path:** `/api/artist/anr/by/social-index` - **Tags:** Artist 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`. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj` (required)** `array` **Items:** - **`code2`** `string | null` - **`id`** `object` - **`image_url`** `string | null` - **`insights`** `object | null` - **`fdiff`** `object` - **`fdiff_percent`** `number | null`, format: `float` - **`sns`** `string | null` - **`value`** `object` - **`name`** `string | null` - **`releases`** `array | null` - **`signed`** `boolean | null` - **`sp_followers`** `integer | null` - **`spotify_artist_ids`** `array | null` - **`tags`** `array | null` - **`twoMonthInsights`** `object | null` - **`fdiff`** `object` - **`fdiff_percent`** `number | null`, format: `float` - **`sns`** `string | null` - **`value`** `object` - **`weekInsights`** `object | null` - **`fdiff`** `object` - **`fdiff_percent`** `number | null`, format: `float` - **`sns`** `string | null` - **`value`** `object` **Example:** ```json { "obj": [ { "id": 0, "name": null, "code2": null, "image_url": null, "tags": [ null ], "spotify_artist_ids": [ "" ], "releases": [ { "cm_album": null, "album_name": null, "release_date": "", "upc": null, "label": null, "image_url": null } ], "insights": { "fdiff": 1, "fdiff_percent": null, "sns": null, "value": 1 }, "weekInsights": { "fdiff": 1, "fdiff_percent": null, "sns": null, "value": 1 }, "twoMonthInsights": { "fdiff": 1, "fdiff_percent": null, "sns": null, "value": 1 }, "sp_followers": null, "signed": null } ] } ``` ### Cross-Platform Performance (CPP) - **Method:** `GET` - **Path:** `/api/artist/{id}/cpp` - **Tags:** Artist 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. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj` (required)** `array` **Items:** - **`rank`** `integer | null` - **`rank_25_75`** `number | null`, format: `float` - **`score`** `number | null`, format: `float` - **`timestp`** `object` **Example:** ```json { "obj": [ { "score": null, "rank": null, "rank_25_75": null, "timestp": "" } ] } ``` ### List Chart Appearances for an Artist - **Method:** `GET` - **Path:** `/api/artist/{id}/{type}/charts` - **Tags:** Artist 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`). Date range up to 365 days between `since` and `until`. Response shape: `{ obj: { data: { entries: [...], uniqueEntities: [...] }, length } }`. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj`** `object` - **`length` (required)** `integer` - **`data`** `object | null` - **`entries`** `array | null` - **`uniqueEntities`** `array | null` **Example:** ```json { "obj": { "data": { "entries": [ { "rank": null, "added_at": "", "code2": null, "plays": 1, "duration": null, "chart_type": null, "chart_name": null, "gnp": null, "pre_rank": null, "peak_rank": null, "peak_date": "", "peak_plays": 1, "total_plays": 1, "id": null, "cm_track": null, "cm_album": null, "name": null, "isrc": null, "image_url": null, "spotify_popularity": null, "spotify_artist_names": [ null ], "track_genre": "", "cm_artist": [ 0 ], "artist_names": [ null ], "code2s": [ null ], "artist_images": [ null ], "artist_covers": [ null ], "spotify_artist_ids": [ "" ], "spotify_track_ids": [ "" ], "spotify_album_ids": [ "" ], "spotify_album_id": null, "spotify_id": null, "spotify_duration_ms": null, "album_ids": [ 0 ], "album_names": [ null ], "album_upc": [ null ], "album_label": [ null ], "release_dates": [ "" ] } ], "uniqueEntities": [ { "entityId": 0, "name": null, "imageUrl": null, "chartEvents": null } ] }, "length": 0 } } ``` ### Get Cross-Platform Artist IDs - **Method:** `GET` - **Path:** `/api/artist/{type}/{id}/get-ids` - **Tags:** Artist 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. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj` (required)** `array` **Items:** - **`amazon_artist_id`** `string | null` - **`amazon_artist_ids`** `array | null` - **`artist_name`** `string | null` - **`chartmetric_id`** `integer | null` - **`cm_artist`** `integer | null` - **`deezer_artist_id`** `string | null` - **`deezer_artist_ids`** `array | null` - **`instagram_id`** `object` - **`itunes_artist_id`** `object` - **`itunes_artist_ids`** `array | null` - **`spotify_artist_id`** `string | null` - **`spotify_artist_ids`** `array | null` - **`youtube_channel_id`** `string | null` - **`youtube_channel_ids`** `array | null` **Example:** ```json { "obj": [ { "cm_artist": null, "chartmetric_id": null, "artist_name": null, "spotify_artist_id": null, "itunes_artist_id": 1, "deezer_artist_id": null, "amazon_artist_id": null, "youtube_channel_id": null, "instagram_id": 1, "spotify_artist_ids": [ "" ], "itunes_artist_ids": [ 1 ], "deezer_artist_ids": [ "" ], "amazon_artist_ids": [ "" ], "youtube_channel_ids": [ "" ] } ] } ``` ### List Artists by Stat Range - **Method:** `GET` - **Path:** `/api/artist/{type}/list` - **Tags:** Artist 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`. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj`** `object` - **`data` (required)** `object` - **`length` (required)** `integer` **Example:** ```json { "obj": { "length": 1, "data": [ { "chartmetric_artist_id": null, "name": null, "code2": null, "genres": "", "cpp_rank": null, "rank_eg": null, "rank_fb": null, "spotify_popularity": null, "spotify_followers": 1, "spotify_monthly_listeners": 1, "spotify_listeners_to_followers_ratio": null, "spotify_followers_to_listeners_ratio": null, "deezer_fans": 1, "facebook_likes": 1, "facebook_talks": 1, "twitter_followers": 1, "twitter_retweets": 1, "instagram_followers": 1, "youtube_channel_views": 1, "youtube_subscribers": 1, "youtube_daily_video_views": 1, "youtube_monthly_video_views": 1, "wikipedia_views": 1, "soundcloud_followers": 1, "bandsintown_followers": 1, "tiktok_followers": 1, "tiktok_likes": 1, "sp_where_people_listen": [ { "code2": null, "listeners": 1, "name": null } ], "signed": null } ] } } ``` ### List Artists (with filters) - **Method:** `GET` - **Path:** `/api/artist/list/filter` - **Tags:** Artist 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`). #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj`** `object` - **`obj` (required)** `array` **Items:** - **`band`** `boolean | null` - **`career_status`** `object | null` - **`stage`** `string | null` - **`stage_score`** `number | null`, format: `float` - **`trend`** `string | null` - **`trend_score`** `number | null`, format: `float` - **`cm_artist`** `object` - **`cm_artist_rank`** `integer | null` - **`cm_tag`** `array | null` - **`code2`** `string | null` - **`current_city`** `string | null` - **`genre_smart_ordered`** `array | null` - **`genres`** `object` - **`hometown_city`** `string | null` - **`image_url`** `string | null` - **`name`** `string | null` - **`pronoun`** `string | null` - **`rank_eg`** `integer | null` - **`rank_fb`** `integer | null` - **`offset` (required)** `integer` - **`total` (required)** `integer` **Example:** ```json { "obj": { "obj": [ { "cm_artist": 0, "name": null, "pronoun": null, "band": null, "image_url": null, "code2": null, "hometown_city": null, "current_city": null, "cm_tag": [ 0 ], "genres": "", "genre_smart_ordered": [ {} ], "career_status": { "stage": null, "stage_score": null, "trend": null, "trend_score": null }, "cm_artist_rank": null, "rank_fb": null, "rank_eg": null } ], "offset": 0, "total": 0 } } ``` ### Artist Metadata - **Method:** `GET` - **Path:** `/api/artist/{id}` - **Tags:** Artist Artist metadata and Chartmetric stats by Chartmetric ID. `cm_statistics` carries a rich per-platform counter + rank map (Spotify, Apple Music, Deezer, Amazon, YouTube, TikTok, Twitter, Instagram, Pandora, Twitch, Line, Boomplay, Shazam, Genius). Cached daily. Pass header `x-accept-partial-data: true` to unblock responses while the artist's ES cache is being rebuilt. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj`** `object` - **`activities`** `array | null` - **`band`** `boolean | null` - **`band_members`** `object` - **`booking_agent`** `string | null` - **`career_status`** `object | null` - **`stage`** `string | null` - **`stage_score`** `number | null`, format: `float` - **`trend`** `string | null` - **`trend_score`** `number | null`, format: `float` - **`cm_artist_rank`** `integer | null` - **`cm_artist_score`** `number | null`, format: `float` - **`cm_statistics`** `object | null` - **`code2`** `string | null` - **`cover_url`** `string | null` - **`created_at`** `object` - **`current_city`** `string | null` - **`current_city_id`** `integer | null` - **`description`** `string | null` - **`gender`** `string | null` - **`gender_title`** `string | null` - **`general_manager`** `string | null` - **`genre_smart_ordered`** `array | null` - **`genreRank`** `object | null` - **`genres`** `object | null` - **`primary`** `object | null` - **`id`** `integer | null` - **`name`** `string | null` - **`score`** `number | null`, format: `float` - **`source`** `string | null` - **`type`** `string | null` - **`secondary`** `array | null` - **`sub`** `array | null` - **`hometown_city`** `string | null` - **`id`** `integer | null` - **`image_url`** `string | null` - **`isni`** `string | null` - **`moods`** `array | null` - **`name`** `string | null` - **`press_contact`** `string | null` - **`pronoun_title`** `string | null` - **`record_label`** `string | null` - **`subGenreRank1`** `object | null` - **`subGenreRank2`** `object | null` - **`topSongwriterCollaborators`** `array | null` **Example:** ```json { "obj": { "id": null, "name": null, "created_at": "", "code2": null, "band": null, "pronoun_title": null, "gender_title": null, "gender": null, "isni": null, "cm_artist_rank": null, "cm_artist_score": null, "cover_url": null, "image_url": null, "hometown_city": null, "current_city": null, "current_city_id": null, "band_members": null, "booking_agent": null, "record_label": null, "press_contact": null, "general_manager": null, "topSongwriterCollaborators": [ null ], "description": null, "genres": { "primary": { "id": null, "name": null, "type": null, "source": null, "score": null }, "secondary": [ { "id": null, "name": null, "type": null, "source": null, "score": null } ], "sub": [ { "id": null, "name": null, "type": null, "source": null, "score": null } ] }, "genre_smart_ordered": [ {} ], "moods": [ { "id": null, "name": null } ], "activities": [ { "id": null, "name": null } ], "career_status": { "stage": null, "stage_score": null, "trend": null, "trend_score": null }, "cm_statistics": {}, "genreRank": {}, "subGenreRank1": {}, "subGenreRank2": {} } } ``` ### Related Artists - **Method:** `GET` - **Path:** `/api/artist/{id}/relatedartists` - **Tags:** Artist 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`. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj` (required)** `array` **Items:** - **`cm_artist_rank`** `integer | null` - **`cm_artist_score`** `number | null`, format: `float` - **`code2`** `string | null` - **`genres`** `object | null` - **`primary`** `object | null` - **`id`** `integer | null` - **`link_type`** `string | null` - **`name`** `string | null` - **`score`** `number | null`, format: `float` - **`secondary`** `array | null` - **`sub`** `array | null` - **`id`** `integer | null` - **`image_url`** `string | null` - **`name`** `string | null` - **`popularity`** `integer | null` - **`preview_track_id`** `object` - **`preview_url`** `string | null` - **`rank_diff`** `integer | null` - **`rank_stats`** `object` - **`sp_followers`** `integer | null` **Example:** ```json { "obj": [ { "id": null, "name": null, "code2": null, "cm_artist_rank": null, "cm_artist_score": null, "image_url": null, "sp_followers": null, "popularity": null, "rank_diff": null, "preview_url": null, "preview_track_id": 0, "genres": { "primary": { "id": null, "name": null, "link_type": null, "score": null }, "secondary": [ { "id": null, "name": null, "link_type": null, "score": null } ], "sub": [ { "id": null, "name": null, "link_type": null, "score": null } ] }, "rank_stats": [ { "rank": null, "timestp": "" } ] } ] } ``` ### Spotify Monthly Listeners by City / Country - **Method:** `GET` - **Path:** `/api/artist/{id}/where-people-listen` - **Tags:** Artist 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`). Rate-limited to 10 requests per second per user. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj`** `object` - **`cities`** `object` - **`countries`** `object` **Example:** ```json { "obj": { "cities": { "additionalProperty": [ { "timestp": "", "code2": null, "spotify_artist_id": null, "lat": null, "lng": null, "region": null, "city_id": null, "spotify_artist_insights_location": 1, "current_max_count": 1, "market_max_cm_artist_id": null, "market_max_artist_name": null, "listeners": 1, "prev_listeners": 1, "artist_city_rank": null, "max_listeners": 1, "population": 1, "city_affinity": 1, "is_estimate": null } ] }, "countries": { "additionalProperty": [ { "timestp": "", "code2": null, "spotify_artist_id": null, "lat": null, "lng": null, "region": null, "city_id": null, "spotify_artist_insights_location": 1, "current_max_count": 1, "market_max_cm_artist_id": null, "market_max_artist_name": null, "listeners": 1, "prev_listeners": 1, "artist_city_rank": null, "max_listeners": 1, "population": 1, "city_affinity": 1, "is_estimate": null } ] } } } ``` ### Playlists Featuring an Artist's Tracks - **Method:** `GET` - **Path:** `/api/artist/{id}/{platform}/{status}/playlists` - **Tags:** Artist Current or past playlists on `platform` (`spotify`, `applemusic`, `deezer`, `amazon`, `youtube`) that feature this artist's tracks. `status` is `current` or `past`. Valid `sortColumn` values vary per `(platform, status)` — e.g. Spotify current supports `added_at`, `code2`, `fdiff_month`, `followers` (default), `name`, `peak_position`, `position`, `track`; Apple Music past supports `removed_at` (default) plus the same stat columns. Flag parameters (editorial, editorialBrand, chart, radio, indie, thisIs, newMusicFriday, ...) also vary per platform — see the apidoc table. When no flags are specified, the query can return an empty array. PG aggregates (`followers`, `fdiff_*`, `num_track`) may surface as strings due to uncast COUNT/SUM. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj` (required)** `array` **Items:** - **`playlist`** `object` - **`active_ratio`** `number | null`, format: `float` - **`added_at`** `object` - **`catalog`** `string | null` - **`cm_track`** `integer | null` - **`code2`** `string | null` - **`curator_name`** `string | null` - **`description`** `string | null` - **`editorial`** `boolean | null` - **`fdiff_month`** `object` - **`fdiff_week`** `object` - **`followers`** `object` - **`id`** `integer | null` - **`image_url`** `string | null` - **`last_updated`** `object` - **`name`** `string | null` - **`num_track`** `object` - **`owner_id`** `object` - **`owner_name`** `string | null` - **`peak_position`** `integer | null` - **`period`** `integer | null` - **`personalized`** `boolean | null` - **`playlist_id`** `object` - **`playlist_image_url`** `string | null` - **`position`** `integer | null` - **`removed_at`** `object` - **`sys_last_updated`** `object` - **`tags`** `array | null` - **`track`** `string | null` - **`track_id`** `integer | null` - **`user_id`** `string | null` - **`track`** `object` - **`album`** `array | null` - **`album_ids`** `array | null` - **`album_label`** `array | null` - **`album_names`** `array | null` - **`album_upc`** `array | null` - **`artist_covers`** `array | null` - **`artist_images`** `array | null` - **`artist_names`** `array | null` - **`cm_artist`** `array | null` - **`cm_track`** `integer | null` - **`code2s`** `array | null` - **`composer_name`** `string | null` - **`id`** `integer | null` - **`image_url`** `string | null` - **`isrc`** `string | null` - **`name`** `string | null` - **`release_dates`** `array | null` - **`score`** `number | null`, format: `float` - **`spotify_album_id`** `string | null` - **`spotify_album_ids`** `array | null` - **`spotify_artist_ids`** `array | null` - **`spotify_artist_names`** `array | null` - **`spotify_duration_ms`** `object` - **`spotify_popularity`** `integer | null` - **`spotify_track_id`** `string | null` - **`spotify_track_ids`** `array | null` - **`track_genre`** `object` **Example:** ```json { "obj": [ { "playlist": { "playlist_id": 0, "track_id": null, "peak_position": null, "position": null, "cm_track": null, "fdiff_month": 1, "fdiff_week": 1, "added_at": "", "removed_at": "", "period": null, "followers": 1, "track": null, "id": null, "name": null, "description": null, "image_url": null, "playlist_image_url": null, "sys_last_updated": "", "last_updated": "", "personalized": null, "code2": null, "curator_name": null, "owner_name": null, "owner_id": 0, "user_id": null, "editorial": null, "tags": [ { "id": null, "name": null } ], "num_track": 1, "catalog": null, "active_ratio": null }, "track": { "id": null, "name": null, "isrc": null, "spotify_track_id": null, "spotify_album_id": null, "image_url": null, "spotify_popularity": null, "cm_track": null, "spotify_artist_names": [ null ], "track_genre": "", "cm_artist": [ 0 ], "artist_names": [ null ], "code2s": [ null ], "artist_images": [ null ], "artist_covers": [ null ], "spotify_artist_ids": [ "" ], "spotify_track_ids": [ "" ], "spotify_album_ids": [ "" ], "spotify_duration_ms": 1, "album_ids": [ 0 ], "album_names": [ null ], "album_upc": [ null ], "album_label": [ null ], "release_dates": [ "" ], "composer_name": null, "score": null, "album": [ { "id": null, "label": null, "name": null, "release_date": "", "upc": null } ] } } ] } ``` ### List Albums Featuring an Artist - **Method:** `GET` - **Path:** `/api/artist/{id}/albums` - **Tags:** Artist 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. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj` (required)** `array` **Items:** - **`artists`** `array | null` - **`cm_album`** `integer | null` - **`cm_label`** `integer | null` - **`created_at`** `object` - **`deezer_album_ids`** `array | null` - **`description`** `string | null` - **`id`** `integer | null` - **`image_url`** `string | null` - **`itunes_album_ids`** `array | null` - **`label`** `string | null` - **`modified_at`** `object` - **`name`** `string | null` - **`num_track`** `object` - **`release_date`** `object` - **`spotify_album_ids`** `array | null` - **`spotify_popularity`** `integer | null` - **`upc`** `string | null` **Example:** ```json { "obj": [ { "id": null, "upc": null, "name": null, "image_url": null, "release_date": "", "label": null, "spotify_popularity": null, "cm_label": null, "description": null, "created_at": "", "modified_at": "", "cm_album": null, "num_track": "", "spotify_album_ids": [ "" ], "itunes_album_ids": [ "" ], "deezer_album_ids": [ "" ], "artists": [ { "cm_artist": null, "name": null, "image_url": null } ] } ] } ``` ### List Tracks by Artist - **Method:** `GET` - **Path:** `/api/artist/{id}/tracks` - **Tags:** Artist 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. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj` (required)** `array` **Items:** - **`album_ids`** `array | null` - **`album_label`** `array | null` - **`album_names`** `array | null` - **`album_upc`** `array | null` - **`amazon_album_ids`** `array | null` - **`amazon_track_ids`** `array | null` - **`artist_covers`** `array | null` - **`artist_images`** `array | null` - **`artist_names`** `array | null` - **`artist_type`** `string | null` - **`cm_artist`** `array | null` - **`cm_audio_features`** `object | null` - **`cm_statistics`** `object | null` - **`cm_track`** `integer | null` - **`cm_track_cluster`** `object | null` - **`cluster_id`** `integer | null` - **`track_types`** `array | null` - **`code2s`** `array | null` - **`created_at`** `object` - **`deezer_album_ids`** `array | null` - **`deezer_duration`** `integer | null` - **`deezer_track_ids`** `array | null` - **`description`** `string | null` - **`genre_smart_ordered`** `array | null` - **`id`** `integer | null` - **`image_url`** `string | null` - **`isrc`** `string | null` - **`itunes_album_ids`** `array | null` - **`itunes_track_ids`** `array | null` - **`modified_at`** `object` - **`name`** `string | null` - **`release_dates`** `array | null` - **`spotify_album_ids`** `array | null` - **`spotify_duration_ms`** `integer | null` - **`spotify_track_ids`** `array | null` - **`storefronts`** `array | null` - **`tags`** `string | null` - **`version_types`** `object | null` - **`total`** `integer | null` **Example:** ```json { "obj": [ { "id": null, "cm_track": null, "isrc": null, "name": null, "image_url": null, "created_at": "", "modified_at": "", "description": null, "tags": null, "artist_type": null, "cm_artist": [ 0 ], "artist_names": [ null ], "code2s": [ null ], "artist_images": [ null ], "artist_covers": [ null ], "spotify_track_ids": [ "" ], "spotify_album_ids": [ "" ], "spotify_duration_ms": null, "itunes_track_ids": [ "" ], "itunes_album_ids": [ "" ], "storefronts": [ "" ], "deezer_track_ids": [ "" ], "deezer_album_ids": [ 1 ], "deezer_duration": null, "amazon_track_ids": [ "" ], "amazon_album_ids": [ "" ], "album_ids": [ 0 ], "album_names": [ null ], "album_upc": [ null ], "album_label": [ null ], "release_dates": [ "" ], "genre_smart_ordered": [ {} ], "cm_statistics": {}, "cm_audio_features": {}, "cm_track_cluster": { "cluster_id": null, "track_types": [ null ] }, "version_types": { "additionalProperty": true } } ], "total": null } ``` ### Artist Social / Streaming Service URLs - **Method:** `GET` - **Path:** `/api/artist/{id}/urls` - **Tags:** Artist 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`, `musicbrainz`, `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). #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj` (required)** `object` **Example:** ```json { "obj": [ { "domain": null, "url": "" } ] } ``` ### Artist Fan Metrics by Source - **Method:** `GET` - **Path:** `/api/artist/{id}/stat/{source}` - **Tags:** Artist Artist's fan-metrics time series for a given `source` (spotify, deezer, facebook, twitter, instagram, youtube\_channel, youtube\_artist, bandsintown, soundcloud, wikipedia, tiktok, twitch, line, melon). Pass `field` to target a single metric — otherwise the handler returns source-specific defaults (e.g. spotify → `followers`, `popularity`, `listeners`, `followers_to_listeners_ratio`). Some `(source, field)` combinations support geo filters (`city_id`, `code2`) — see the apidoc table. 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 `interpolated: true|false` inside each point). #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj`** `object` - **`artist_likes`** `array` **Items:** - **`daily_diff`** `object` - **`diff`** `object` - **`extrapolated`** `boolean | null` - **`flags`** `boolean | null` - **`interpolated`** `boolean | null` - **`monthly_diff`** `object` - **`monthly_diff_percent`** `number | null`, format: `float` - **`timestp`** `object` - **`value`** `object` - **`weekly_diff`** `object` - **`weekly_diff_percent`** `number | null`, format: `float` - **`comments`** `array` **Items:** - **`daily_diff`** `object` - **`diff`** `object` - **`extrapolated`** `boolean | null` - **`flags`** `boolean | null` - **`interpolated`** `boolean | null` - **`monthly_diff`** `object` - **`monthly_diff_percent`** `number | null`, format: `float` - **`timestp`** `object` - **`value`** `object` - **`weekly_diff`** `object` - **`weekly_diff_percent`** `number | null`, format: `float` - **`daily_views`** `array` **Items:** - **`daily_diff`** `object` - **`diff`** `object` - **`extrapolated`** `boolean | null` - **`flags`** `boolean | null` - **`interpolated`** `boolean | null` - **`monthly_diff`** `object` - **`monthly_diff_percent`** `number | null`, format: `float` - **`timestp`** `object` - **`value`** `object` - **`weekly_diff`** `object` - **`weekly_diff_percent`** `number | null`, format: `float` - **`fans`** `array` **Items:** - **`daily_diff`** `object` - **`diff`** `object` - **`extrapolated`** `boolean | null` - **`flags`** `boolean | null` - **`interpolated`** `boolean | null` - **`monthly_diff`** `object` - **`monthly_diff_percent`** `number | null`, format: `float` - **`timestp`** `object` - **`value`** `object` - **`weekly_diff`** `object` - **`weekly_diff_percent`** `number | null`, format: `float` - **`follower_count`** `array` **Items:** - **`daily_diff`** `object` - **`diff`** `object` - **`extrapolated`** `boolean | null` - **`flags`** `boolean | null` - **`interpolated`** `boolean | null` - **`monthly_diff`** `object` - **`monthly_diff_percent`** `number | null`, format: `float` - **`timestp`** `object` - **`value`** `object` - **`weekly_diff`** `object` - **`weekly_diff_percent`** `number | null`, format: `float` - **`followers`** `array` **Items:** - **`daily_diff`** `object` - **`diff`** `object` - **`extrapolated`** `boolean | null` - **`flags`** `boolean | null` - **`interpolated`** `boolean | null` - **`monthly_diff`** `object` - **`monthly_diff_percent`** `number | null`, format: `float` - **`timestp`** `object` - **`value`** `object` - **`weekly_diff`** `object` - **`weekly_diff_percent`** `number | null`, format: `float` - **`followers_to_listeners_ratio`** `array` **Items:** - **`daily_diff`** `object` - **`diff`** `object` - **`extrapolated`** `boolean | null` - **`flags`** `boolean | null` - **`interpolated`** `boolean | null` - **`monthly_diff`** `object` - **`monthly_diff_percent`** `number | null`, format: `float` - **`timestp`** `object` - **`value`** `object` - **`weekly_diff`** `object` - **`weekly_diff_percent`** `number | null`, format: `float` - **`likes`** `array` **Items:** - **`daily_diff`** `object` - **`diff`** `object` - **`extrapolated`** `boolean | null` - **`flags`** `boolean | null` - **`interpolated`** `boolean | null` - **`monthly_diff`** `object` - **`monthly_diff_percent`** `number | null`, format: `float` - **`timestp`** `object` - **`value`** `object` - **`weekly_diff`** `object` - **`weekly_diff_percent`** `number | null`, format: `float` - **`link`** `string | null` - **`listeners`** `array` **Items:** - **`daily_diff`** `object` - **`diff`** `object` - **`extrapolated`** `boolean | null` - **`flags`** `boolean | null` - **`interpolated`** `boolean | null` - **`monthly_diff`** `object` - **`monthly_diff_percent`** `number | null`, format: `float` - **`timestp`** `object` - **`value`** `object` - **`weekly_diff`** `object` - **`weekly_diff_percent`** `number | null`, format: `float` - **`monthly_viewer_hours`** `array` **Items:** - **`daily_diff`** `object` - **`diff`** `object` - **`extrapolated`** `boolean | null` - **`flags`** `boolean | null` - **`interpolated`** `boolean | null` - **`monthly_diff`** `object` - **`monthly_diff_percent`** `number | null`, format: `float` - **`timestp`** `object` - **`value`** `object` - **`weekly_diff`** `object` - **`weekly_diff_percent`** `number | null`, format: `float` - **`monthly_views`** `array` **Items:** - **`daily_diff`** `object` - **`diff`** `object` - **`extrapolated`** `boolean | null` - **`flags`** `boolean | null` - **`interpolated`** `boolean | null` - **`monthly_diff`** `object` - **`monthly_diff_percent`** `number | null`, format: `float` - **`timestp`** `object` - **`value`** `object` - **`weekly_diff`** `object` - **`weekly_diff_percent`** `number | null`, format: `float` - **`popularity`** `array` **Items:** - **`daily_diff`** `object` - **`diff`** `object` - **`extrapolated`** `boolean | null` - **`flags`** `boolean | null` - **`interpolated`** `boolean | null` - **`monthly_diff`** `object` - **`monthly_diff_percent`** `number | null`, format: `float` - **`timestp`** `object` - **`value`** `object` - **`weekly_diff`** `object` - **`weekly_diff_percent`** `number | null`, format: `float` - **`retweets`** `array` **Items:** - **`daily_diff`** `object` - **`diff`** `object` - **`extrapolated`** `boolean | null` - **`flags`** `boolean | null` - **`interpolated`** `boolean | null` - **`monthly_diff`** `object` - **`monthly_diff_percent`** `number | null`, format: `float` - **`timestp`** `object` - **`value`** `object` - **`weekly_diff`** `object` - **`weekly_diff_percent`** `number | null`, format: `float` - **`subscribers`** `array` **Items:** - **`daily_diff`** `object` - **`diff`** `object` - **`extrapolated`** `boolean | null` - **`flags`** `boolean | null` - **`interpolated`** `boolean | null` - **`monthly_diff`** `object` - **`monthly_diff_percent`** `number | null`, format: `float` - **`timestp`** `object` - **`value`** `object` - **`weekly_diff`** `object` - **`weekly_diff_percent`** `number | null`, format: `float` - **`talks`** `array` **Items:** - **`daily_diff`** `object` - **`diff`** `object` - **`extrapolated`** `boolean | null` - **`flags`** `boolean | null` - **`interpolated`** `boolean | null` - **`monthly_diff`** `object` - **`monthly_diff_percent`** `number | null`, format: `float` - **`timestp`** `object` - **`value`** `object` - **`weekly_diff`** `object` - **`weekly_diff_percent`** `number | null`, format: `float` - **`videos`** `array` **Items:** - **`daily_diff`** `object` - **`diff`** `object` - **`extrapolated`** `boolean | null` - **`flags`** `boolean | null` - **`interpolated`** `boolean | null` - **`monthly_diff`** `object` - **`monthly_diff_percent`** `number | null`, format: `float` - **`timestp`** `object` - **`value`** `object` - **`weekly_diff`** `object` - **`weekly_diff_percent`** `number | null`, format: `float` - **`views`** `array` **Items:** - **`daily_diff`** `object` - **`diff`** `object` - **`extrapolated`** `boolean | null` - **`flags`** `boolean | null` - **`interpolated`** `boolean | null` - **`monthly_diff`** `object` - **`monthly_diff_percent`** `number | null`, format: `float` - **`timestp`** `object` - **`value`** `object` - **`weekly_diff`** `object` - **`weekly_diff_percent`** `number | null`, format: `float` - **`weekly_viewer_hours`** `array` **Items:** - **`daily_diff`** `object` - **`diff`** `object` - **`extrapolated`** `boolean | null` - **`flags`** `boolean | null` - **`interpolated`** `boolean | null` - **`monthly_diff`** `object` - **`monthly_diff_percent`** `number | null`, format: `float` - **`timestp`** `object` - **`value`** `object` - **`weekly_diff`** `object` - **`weekly_diff_percent`** `number | null`, format: `float` **Example:** ```json { "obj": { "link": null, "followers": [ { "value": 1, "timestp": "", "flags": null, "diff": 1, "weekly_diff": 1, "weekly_diff_percent": null, "monthly_diff": 1, "monthly_diff_percent": null, "daily_diff": 1, "interpolated": null, "extrapolated": null } ], "popularity": [ { "value": 1, "timestp": "", "flags": null, "diff": 1, "weekly_diff": 1, "weekly_diff_percent": null, "monthly_diff": 1, "monthly_diff_percent": null, "daily_diff": 1, "interpolated": null, "extrapolated": null } ], "listeners": [ { "value": 1, "timestp": "", "flags": null, "diff": 1, "weekly_diff": 1, "weekly_diff_percent": null, "monthly_diff": 1, "monthly_diff_percent": null, "daily_diff": 1, "interpolated": null, "extrapolated": null } ], "followers_to_listeners_ratio": [ { "value": 1, "timestp": "", "flags": null, "diff": 1, "weekly_diff": 1, "weekly_diff_percent": null, "monthly_diff": 1, "monthly_diff_percent": null, "daily_diff": 1, "interpolated": null, "extrapolated": null } ], "fans": [ { "value": 1, "timestp": "", "flags": null, "diff": 1, "weekly_diff": 1, "weekly_diff_percent": null, "monthly_diff": 1, "monthly_diff_percent": null, "daily_diff": 1, "interpolated": null, "extrapolated": null } ], "likes": [ { "value": 1, "timestp": "", "flags": null, "diff": 1, "weekly_diff": 1, "weekly_diff_percent": null, "monthly_diff": 1, "monthly_diff_percent": null, "daily_diff": 1, "interpolated": null, "extrapolated": null } ], "talks": [ { "value": 1, "timestp": "", "flags": null, "diff": 1, "weekly_diff": 1, "weekly_diff_percent": null, "monthly_diff": 1, "monthly_diff_percent": null, "daily_diff": 1, "interpolated": null, "extrapolated": null } ], "retweets": [ { "value": 1, "timestp": "", "flags": null, "diff": 1, "weekly_diff": 1, "weekly_diff_percent": null, "monthly_diff": 1, "monthly_diff_percent": null, "daily_diff": 1, "interpolated": null, "extrapolated": null } ], "subscribers": [ { "value": 1, "timestp": "", "flags": null, "diff": 1, "weekly_diff": 1, "weekly_diff_percent": null, "monthly_diff": 1, "monthly_diff_percent": null, "daily_diff": 1, "interpolated": null, "extrapolated": null } ], "views": [ { "value": 1, "timestp": "", "flags": null, "diff": 1, "weekly_diff": 1, "weekly_diff_percent": null, "monthly_diff": 1, "monthly_diff_percent": null, "daily_diff": 1, "interpolated": null, "extrapolated": null } ], "videos": [ { "value": 1, "timestp": "", "flags": null, "diff": 1, "weekly_diff": 1, "weekly_diff_percent": null, "monthly_diff": 1, "monthly_diff_percent": null, "daily_diff": 1, "interpolated": null, "extrapolated": null } ], "comments": [ { "value": 1, "timestp": "", "flags": null, "diff": 1, "weekly_diff": 1, "weekly_diff_percent": null, "monthly_diff": 1, "monthly_diff_percent": null, "daily_diff": 1, "interpolated": null, "extrapolated": null } ], "daily_views": [ { "value": 1, "timestp": "", "flags": null, "diff": 1, "weekly_diff": 1, "weekly_diff_percent": null, "monthly_diff": 1, "monthly_diff_percent": null, "daily_diff": 1, "interpolated": null, "extrapolated": null } ], "monthly_views": [ { "value": 1, "timestp": "", "flags": null, "diff": 1, "weekly_diff": 1, "weekly_diff_percent": null, "monthly_diff": 1, "monthly_diff_percent": null, "daily_diff": 1, "interpolated": null, "extrapolated": null } ], "follower_count": [ { "value": 1, "timestp": "", "flags": null, "diff": 1, "weekly_diff": 1, "weekly_diff_percent": null, "monthly_diff": 1, "monthly_diff_percent": null, "daily_diff": 1, "interpolated": null, "extrapolated": null } ], "monthly_viewer_hours": [ { "value": 1, "timestp": "", "flags": null, "diff": 1, "weekly_diff": 1, "weekly_diff_percent": null, "monthly_diff": 1, "monthly_diff_percent": null, "daily_diff": 1, "interpolated": null, "extrapolated": null } ], "weekly_viewer_hours": [ { "value": 1, "timestp": "", "flags": null, "diff": 1, "weekly_diff": 1, "weekly_diff_percent": null, "monthly_diff": 1, "monthly_diff_percent": null, "daily_diff": 1, "interpolated": null, "extrapolated": null } ], "artist_likes": [ { "value": 1, "timestp": "", "flags": null, "diff": 1, "weekly_diff": 1, "weekly_diff_percent": null, "monthly_diff": 1, "monthly_diff_percent": null, "daily_diff": 1, "interpolated": null, "extrapolated": null } ] } } ``` ### Instagram Audience Stats - **Method:** `GET` - **Path:** `/api/artist/{id}/instagram-audience-stats` - **Tags:** Artist 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_commments_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`. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj`** `object` - **`audience_brand_affinities`** `array` **Items:** - **`affinity`** `number | null`, format: `float` - **`name`** `string | null` - **`weight`** `string | null` - **`audience_ethnicities`** `array` **Items:** - **`code`** `string | null` - **`name`** `string | null` - **`weight`** `string | null` - **`audience_genders`** `array` **Items:** - **`code`** `string | null` - **`weight`** `string | null` - **`audience_genders_per_age`** `array` **Items:** - **`code`** `string | null` - **`female`** `string | null` - **`male`** `string | null` - **`audience_interests`** `array` **Items:** - **`affinity`** `number | null`, format: `float` - **`name`** `string | null` - **`weight`** `string | null` - **`audience_likers_brand_affinities`** `array` **Items:** - **`affinity`** `number | null`, format: `float` - **`name`** `string | null` - **`weight`** `string | null` - **`audience_likers_ethnicities`** `array` **Items:** - **`code`** `string | null` - **`name`** `string | null` - **`weight`** `string | null` - **`audience_likers_genders`** `array` **Items:** - **`code`** `string | null` - **`weight`** `string | null` - **`audience_likers_genders_per_age`** `array` **Items:** - **`code`** `string | null` - **`female`** `string | null` - **`male`** `string | null` - **`audience_likers_interests`** `array` **Items:** - **`affinity`** `number | null`, format: `float` - **`name`** `string | null` - **`weight`** `string | null` - **`avg_commments_per_post`** `integer | null` - **`avg_likes_per_post`** `integer | null` - **`engagement_rate`** `number | null`, format: `float` - **`followers`** `integer | null` - **`likers_top_cities`** `array` **Items:** - **`country`** `string | null` - **`followers`** `integer | null` - **`likes`** `integer | null` - **`name`** `string | null` - **`percent`** `string | null` - **`state`** `string | null` - **`likers_top_countries`** `array` **Items:** - **`code`** `string | null` - **`comments`** `integer | null` - **`followers`** `integer | null` - **`likes`** `integer | null` - **`name`** `string | null` - **`percent`** `string | null` - **`subscribers`** `integer | null` - **`notable_followers`** `array` **Items:** - **`avg_likes`** `integer | null` - **`avg_views`** `integer | null` - **`custom_name`** `string | null` - **`engagements`** `object` - **`followers`** `integer | null` - **`fullname`** `string | null` - **`geo`** `object | null` - **`handle`** `string | null` - **`is_verified`** `object` - **`picture`** `string | null` - **`subscribers`** `integer | null` - **`url`** `string | null` - **`user_id`** `object` - **`username`** `string | null` - **`timestp`** `string | null` - **`top_cities`** `array` **Items:** - **`country`** `string | null` - **`followers`** `integer | null` - **`likes`** `integer | null` - **`name`** `string | null` - **`percent`** `string | null` - **`state`** `string | null` - **`top_countries`** `array` **Items:** - **`code`** `string | null` - **`comments`** `integer | null` - **`followers`** `integer | null` - **`likes`** `integer | null` - **`name`** `string | null` - **`percent`** `string | null` - **`subscribers`** `integer | null` **Example:** ```json { "obj": { "top_countries": [ { "name": null, "code": null, "percent": null, "followers": null, "subscribers": null, "likes": null, "comments": null } ], "top_cities": [ { "name": null, "state": null, "country": null, "percent": null, "followers": null, "likes": null } ], "likers_top_countries": [ { "name": null, "code": null, "percent": null, "followers": null, "subscribers": null, "likes": null, "comments": null } ], "likers_top_cities": [ { "name": null, "state": null, "country": null, "percent": null, "followers": null, "likes": null } ], "audience_genders_per_age": [ { "code": null, "male": null, "female": null } ], "audience_ethnicities": [ { "code": null, "name": null, "weight": null } ], "audience_genders": [ { "code": null, "weight": null } ], "audience_brand_affinities": [ { "name": null, "weight": null, "affinity": null } ], "audience_interests": [ { "name": null, "weight": null, "affinity": null } ], "audience_likers_genders_per_age": [ { "code": null, "male": null, "female": null } ], "audience_likers_ethnicities": [ { "code": null, "name": null, "weight": null } ], "audience_likers_genders": [ { "code": null, "weight": null } ], "audience_likers_brand_affinities": [ { "name": null, "weight": null, "affinity": null } ], "audience_likers_interests": [ { "name": null, "weight": null, "affinity": null } ], "notable_followers": [ { "user_id": "", "username": null, "custom_name": null, "handle": null, "picture": null, "fullname": null, "url": null, "followers": null, "subscribers": null, "is_verified": true, "engagements": 1, "avg_likes": null, "avg_views": null, "geo": {} } ], "followers": null, "avg_likes_per_post": null, "avg_commments_per_post": null, "engagement_rate": null, "timestp": null } } ``` ### Instagram Audience Stats Available Dates - **Method:** `GET` - **Path:** `/api/artist/{id}/instagram-audience-stats/dates` - **Tags:** Artist 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. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj`** `object` - **`dates` (required)** `array` **Items:** `[ "string", "null" ]` **Example:** ```json { "obj": { "dates": [ null ] } } ``` ### Social Audience Stats Time Series - **Method:** `GET` - **Path:** `/api/artist/{id}/social-audience-stats` - **Tags:** Artist Time-series of Instagram / TikTok / YouTube audience stats. Pass `domain` (`instagram`, `tiktok`, `youtube`), `audienceType` (`followers`, `likes`, `notable_followers`, ...), 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. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj` (required)** `array` **Items:** - **`avg_comments_per_post`** `object` - **`avg_likes_per_post`** `object` - **`avg_views_per_post`** `object` - **`brand_followers`** `object` - **`brand_id`** `object` - **`brand_name`** `string | null` - **`city_affinity`** `number | null`, format: `float` - **`city_id`** `object` - **`city_name`** `string | null` - **`code2`** `string | null` - **`engagement_rate`** `number | null`, format: `float` - **`followers`** `object` - **`interest_followers`** `object` - **`interest_id`** `object` - **`interest_name`** `string | null` - **`language_name`** `string | null` - **`lat`** `number | null`, format: `float` - **`lng`** `number | null`, format: `float` - **`name`** `string | null` - **`rank`** `integer | null` - **`scale`** `number | null`, format: `float` - **`timestp`** `object` - **`value`** `object` - **`weight`** `object` - **`weights`** `object` **Example:** ```json { "obj": [ { "timestp": "", "followers": 1, "avg_likes_per_post": 1, "avg_comments_per_post": 1, "avg_views_per_post": 1, "engagement_rate": null, "code2": null, "rank": null, "weights": 1, "name": null, "lat": null, "lng": null, "city_id": 0, "city_name": null, "city_affinity": null, "value": 1, "language_name": null, "brand_id": 0, "brand_name": null, "brand_followers": 1, "interest_id": 0, "interest_name": null, "interest_followers": 1, "weight": 1, "scale": null } ] } ``` ### YouTube Audience Stats - **Method:** `GET` - **Path:** `/api/artist/{id}/youtube-audience-stats` - **Tags:** Artist 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_commments_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`). #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj`** `object` - **`audience_genders`** `array` **Items:** - **`code`** `string | null` - **`weight`** `string | null` - **`audience_genders_per_age`** `array` **Items:** - **`code`** `string | null` - **`female`** `string | null` - **`male`** `string | null` - **`avg_commments_per_post`** `integer | null` - **`avg_likes_per_post`** `integer | null` - **`commenters_genders`** `array` **Items:** - **`code`** `string | null` - **`weight`** `string | null` - **`commenters_genders_per_age`** `array` **Items:** - **`code`** `string | null` - **`female`** `string | null` - **`male`** `string | null` - **`commenters_top_countries`** `array` **Items:** - **`code`** `string | null` - **`comments`** `integer | null` - **`followers`** `integer | null` - **`likes`** `integer | null` - **`name`** `string | null` - **`percent`** `string | null` - **`subscribers`** `integer | null` - **`engagement_rate`** `number | null`, format: `float` - **`last_updated_timestamp`** `object` - **`notable_subscribers`** `array` **Items:** - **`avg_likes`** `integer | null` - **`avg_views`** `integer | null` - **`custom_name`** `string | null` - **`engagements`** `object` - **`followers`** `integer | null` - **`fullname`** `string | null` - **`geo`** `object | null` - **`handle`** `string | null` - **`is_verified`** `object` - **`picture`** `string | null` - **`subscribers`** `integer | null` - **`url`** `string | null` - **`user_id`** `object` - **`username`** `string | null` - **`subscribers`** `integer | null` - **`timestp`** `object` - **`top_countries`** `array` **Items:** - **`code`** `string | null` - **`comments`** `integer | null` - **`followers`** `integer | null` - **`likes`** `integer | null` - **`name`** `string | null` - **`percent`** `string | null` - **`subscribers`** `integer | null` **Example:** ```json { "obj": { "top_countries": [ { "name": null, "code": null, "percent": null, "followers": null, "subscribers": null, "likes": null, "comments": null } ], "commenters_top_countries": [ { "name": null, "code": null, "percent": null, "followers": null, "subscribers": null, "likes": null, "comments": null } ], "audience_genders_per_age": [ { "code": null, "male": null, "female": null } ], "audience_genders": [ { "code": null, "weight": null } ], "commenters_genders_per_age": [ { "code": null, "male": null, "female": null } ], "commenters_genders": [ { "code": null, "weight": null } ], "notable_subscribers": [ { "user_id": "", "username": null, "custom_name": null, "handle": null, "picture": null, "fullname": null, "url": null, "followers": null, "subscribers": null, "is_verified": true, "engagements": 1, "avg_likes": null, "avg_views": null, "geo": {} } ], "subscribers": null, "avg_likes_per_post": null, "avg_commments_per_post": null, "engagement_rate": null, "last_updated_timestamp": "", "timestp": "" } } ``` ### TikTok Audience Stats - **Method:** `GET` - **Path:** `/api/artist/{id}/tiktok-audience-stats` - **Tags:** Artist 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_commments_per_post`, `engagement_rate`). Rate fields come from uncast PG numerics so may surface as strings. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj`** `object` - **`audience_genders`** `array` **Items:** - **`code`** `string | null` - **`weight`** `string | null` - **`audience_genders_per_age`** `array` **Items:** - **`code`** `string | null` - **`female`** `string | null` - **`male`** `string | null` - **`avg_commments_per_post`** `object` - **`avg_likes_per_post`** `object` - **`engagement_rate`** `object` - **`followers`** `integer | null` - **`notable_followers`** `array` **Items:** - **`avg_likes`** `integer | null` - **`avg_views`** `integer | null` - **`custom_name`** `string | null` - **`engagements`** `object` - **`followers`** `integer | null` - **`fullname`** `string | null` - **`geo`** `object | null` - **`handle`** `string | null` - **`is_verified`** `object` - **`picture`** `string | null` - **`subscribers`** `integer | null` - **`url`** `string | null` - **`user_id`** `object` - **`username`** `string | null` - **`timestp`** `object` - **`top_countries`** `array` **Items:** - **`code`** `string | null` - **`comments`** `integer | null` - **`followers`** `integer | null` - **`likes`** `integer | null` - **`name`** `string | null` - **`percent`** `string | null` - **`subscribers`** `integer | null` **Example:** ```json { "obj": { "top_countries": [ { "name": null, "code": null, "percent": null, "followers": null, "subscribers": null, "likes": null, "comments": null } ], "audience_genders_per_age": [ { "code": null, "male": null, "female": null } ], "audience_genders": [ { "code": null, "weight": null } ], "notable_followers": [ { "user_id": "", "username": null, "custom_name": null, "handle": null, "picture": null, "fullname": null, "url": null, "followers": null, "subscribers": null, "is_verified": true, "engagements": 1, "avg_likes": null, "avg_views": null, "geo": {} } ], "followers": null, "avg_likes_per_post": 1, "avg_commments_per_post": 1, "engagement_rate": 1, "timestp": "" } } ``` ### Artist Top Tracks by Source - **Method:** `GET` - **Path:** `/api/artist/{id}/top-tracks/{source}` - **Tags:** Artist Top tracks for an artist on a given short-form / social platform. `source` is one of `tiktok`, `youtube_shorts`, `instagram`, `instagram_reels`. 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). #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj` (required)** `array` **Items:** - **`audio_url`** `string | null` - **`cm_track`** `object` - **`comments`** `object` - **`created_at`** `object` - **`engagementRate`** `number | null`, format: `float` - **`image_url`** `string | null` - **`isrc`** `string | null` - **`likes`** `object` - **`monthly_diff_percent`** `number | null`, format: `float` - **`name`** `string | null` - **`posts`** `object` - **`score`** `number | null`, format: `float` - **`sound_id`** `object` - **`tags`** `string | null` - **`tiktok`** `object` - **`tiktok_track_id`** `object` - **`tiktok_url`** `string | null` - **`track_image_url`** `string | null` - **`track_name`** `string | null` - **`trend`** `array | null` - **`upload_date`** `object` - **`views`** `object` - **`views_percentage`** `object` **Example:** ```json { "obj": [ { "cm_track": 0, "name": null, "track_name": null, "image_url": null, "track_image_url": null, "audio_url": null, "isrc": null, "tiktok": 1, "tiktok_track_id": 1, "tiktok_url": null, "sound_id": 1, "tags": null, "views": 1, "likes": 1, "comments": 1, "posts": 1, "views_percentage": 1, "upload_date": "", "created_at": "", "monthly_diff_percent": null, "score": null, "trend": [ { "timestp": "", "value": 1 } ], "engagementRate": null } ] } ``` ### Artist Rank (Latest) - **Method:** `GET` - **Path:** `/api/artist/{id}/artist-rank` - **Tags:** Artist 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. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj`** `object | null` - **`artist_rank`** `integer | null` **Example:** ```json { "obj": { "artist_rank": null } } ``` ### Artist Rank on Historical Date - **Method:** `GET` - **Path:** `/api/artist/{id}/past-artist-rank` - **Tags:** Artist 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. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj` (required)** `array` **Items:** - **`artist_rank`** `integer | null` - **`code2`** `string | null` - **`genre`** `string | null` - **`genre_id`** `integer | null` **Example:** ```json { "obj": [ { "artist_rank": null, "code2": null, "genre_id": null, "genre": null } ] } ``` ### Neighboring Artists - **Method:** `GET` - **Path:** `/api/artist/{id}/neighboring-artists` - **Tags:** Artist 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. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj`** `object` **Example:** ```json { "obj": [ { "id": null, "name": null, "pronoun": null, "band": null, "image_url": null, "preview_url": null, "code2": null, "cm_tag": [], "cm_tag_rank": [ { "cm_tag": 0, "rank": 1, "name": null, "primary": true } ], "position": 1, "country_rank": 1, "country_rank_code2": null, "genres": null } ] } ``` ### YouTube Views & Market Coverage - **Method:** `GET` - **Path:** `/api/artist/{id}/market-coverage-views/youtube` - **Tags:** Artist 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. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj`** `object` - **`artistTotalViews`** `object` - **`insights`** `object` - **`cities`** `array` **Items:** - **`city_id`** `integer | null` - **`code2`** `string | null` - **`continent`** `string | null` - **`current_max_count`** `object` - **`lat`** `number | null`, format: `float` - **`lng`** `number | null`, format: `float` - **`market_max_artist_name`** `string | null` - **`market_max_cm_artist_id`** `object` - **`name`** `string | null` - **`params_id`** `string | null` - **`rank`** `integer | null` - **`region`** `string | null` - **`timestp`** `object` - **`trend`** `array | null` - **`value`** `object` - **`countries`** `array` **Items:** - **`city_id`** `integer | null` - **`code2`** `string | null` - **`continent`** `string | null` - **`current_max_count`** `object` - **`lat`** `number | null`, format: `float` - **`lng`** `number | null`, format: `float` - **`market_max_artist_name`** `string | null` - **`market_max_cm_artist_id`** `object` - **`name`** `string | null` - **`params_id`** `string | null` - **`rank`** `integer | null` - **`region`** `string | null` - **`timestp`** `object` - **`trend`** `array | null` - **`value`** `object` - **`marketInsights`** `object` - **`marketCities`** `array` **Items:** - **`city_id`** `integer | null` - **`code2`** `string | null` - **`continent`** `string | null` - **`current_max_count`** `object` - **`lat`** `number | null`, format: `float` - **`lng`** `number | null`, format: `float` - **`market_max_artist_name`** `string | null` - **`market_max_cm_artist_id`** `object` - **`name`** `string | null` - **`params_id`** `string | null` - **`rank`** `integer | null` - **`region`** `string | null` - **`timestp`** `object` - **`trend`** `array | null` - **`value`** `object` - **`marketCountries`** `array` **Items:** - **`city_id`** `integer | null` - **`code2`** `string | null` - **`continent`** `string | null` - **`current_max_count`** `object` - **`lat`** `number | null`, format: `float` - **`lng`** `number | null`, format: `float` - **`market_max_artist_name`** `string | null` - **`market_max_cm_artist_id`** `object` - **`name`** `string | null` - **`params_id`** `string | null` - **`rank`** `integer | null` - **`region`** `string | null` - **`timestp`** `object` - **`trend`** `array | null` - **`value`** `object` **Example:** ```json { "obj": { "insights": { "cities": [ { "rank": null, "value": 1, "timestp": "", "params_id": null, "name": null, "lat": null, "lng": null, "code2": null, "city_id": null, "current_max_count": 1, "region": null, "market_max_cm_artist_id": 0, "market_max_artist_name": null, "continent": null, "trend": [ { "timestp": "", "monthlyViews": 1 } ] } ], "countries": [ { "rank": null, "value": 1, "timestp": "", "params_id": null, "name": null, "lat": null, "lng": null, "code2": null, "city_id": null, "current_max_count": 1, "region": null, "market_max_cm_artist_id": 0, "market_max_artist_name": null, "continent": null, "trend": [ { "timestp": "", "monthlyViews": 1 } ] } ] }, "marketInsights": { "marketCities": [ { "rank": null, "value": 1, "timestp": "", "params_id": null, "name": null, "lat": null, "lng": null, "code2": null, "city_id": null, "current_max_count": 1, "region": null, "market_max_cm_artist_id": 0, "market_max_artist_name": null, "continent": null, "trend": [ { "timestp": "", "monthlyViews": 1 } ] } ], "marketCountries": [ { "rank": null, "value": 1, "timestp": "", "params_id": null, "name": null, "lat": null, "lng": null, "code2": null, "city_id": null, "current_max_count": 1, "region": null, "market_max_cm_artist_id": 0, "market_max_artist_name": null, "continent": null, "trend": [ { "timestp": "", "monthlyViews": 1 } ] } ] }, "artistTotalViews": 1 } } ``` ### TV Show Appearances - **Method:** `GET` - **Path:** `/api/artist/{id}/tvmaze` - **Tags:** Artist 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. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj`** `object` - **`people` (required)** `array` **Items:** - **`cm_artist`** `integer | null` - **`country_code`** `string | null` - **`created_at`** `object` - **`date_of_birth`** `object` - **`date_of_death`** `object` - **`gender`** `integer | null` - **`id`** `integer | null` - **`image`** `string | null` - **`modified_at`** `object` - **`name`** `string | null` - **`tv_maze_url`** `string | null` - **`shows` (required)** `array` **Items:** - **`as`** `string | null` - **`episodes`** `array | null` - **`show_details`** `object | null` - **`created_at`** `object` - **`genres`** `array | null` - **`id`** `integer | null` - **`image`** `string | null` - **`modified_at`** `object` - **`name`** `string | null` - **`officialsite`** `string | null` - **`premiered`** `object` - **`rating`** `object` - **`runtime`** `integer | null` - **`summary`** `string | null` - **`tv_maze_url`** `string | null` - **`title`** `string | null` - **`url`** `string | null` - **`year`** `string | null` **Example:** ```json { "obj": { "people": [ { "id": null, "name": null, "gender": null, "image": null, "date_of_birth": "", "date_of_death": "", "country_code": null, "tv_maze_url": null, "cm_artist": null, "created_at": "", "modified_at": "" } ], "shows": [ { "title": null, "as": null, "url": null, "year": null, "episodes": [ { "id": null, "title": null, "url": null, "date": null } ], "show_details": { "id": null, "name": null, "genres": [ null ], "runtime": null, "premiered": "", "officialsite": null, "rating": "", "image": null, "summary": null, "tv_maze_url": null, "created_at": "", "modified_at": "" } } ] } } ``` ### Career History - **Method:** `GET` - **Path:** `/api/artist/{id}/career` - **Tags:** Artist 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. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj` (required)** `array` **Items:** - **`momentum`** `string | null` - **`momentum_score`** `object` - **`stage`** `string | null` - **`stage_score`** `object` - **`timestp`** `object` **Example:** ```json { "obj": [ { "timestp": "", "stage": null, "stage_score": 1, "momentum": null, "momentum_score": 1 } ] } ``` ### Milestones - **Method:** `GET` - **Path:** `/api/artist/{id}/milestones` - **Tags:** Artist 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. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj`** `object` - **`insights` (required)** `array` **Items:** - **`artist_name`** `string | null` - **`date`** `object` - **`group_size`** `object` - **`id`** `object` - **`platform`** `string | null` - **`stars`** `integer | null` - **`summary`** `string | null` - **`track_name`** `string | null` - **`count`** `object` **Example:** ```json { "obj": { "insights": [ { "id": 0, "date": "", "summary": null, "artist_name": null, "track_name": null, "platform": null, "stars": null, "group_size": null } ], "count": 0 } } ``` ### Noteworthy Insights - **Method:** `GET` - **Path:** `/api/artist/{id}/noteworthy-insights` - **Tags:** Artist 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`. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj` (required)** `array` **Items:** - **`categories`** `array | null` - **`code2`** `string | null` - **`graphImageUrl`** `string | null` - **`insight`** `string | null` - **`insightDate`** `object` - **`insightDateMinus7Days`** `object` - **`insightId`** `object` - **`insightType`** `string | null` - **`metricDx1`** `object` - **`metricDx2`** `object` - **`metricName`** `string | null` - **`platform`** `string | null` - **`target`** `string | null` - **`targetId`** `object` - **`targetImageUrl`** `string | null` - **`targetName`** `string | null` - **`title`** `string | null` - **`variant`** `string | null` **Example:** ```json { "obj": [ { "insight": null, "variant": null, "insightType": null, "metricName": null, "insightId": 0, "target": null, "targetId": 0, "targetName": null, "targetImageUrl": null, "title": null, "insightDate": "", "insightDateMinus7Days": "", "graphImageUrl": null, "code2": null, "platform": null, "categories": [], "metricDx1": 1, "metricDx2": 1 } ] } ``` ### Live Events - **Method:** `GET` - **Path:** `/api/artist/{id}/{status}/events` - **Tags:** Artist Live events (concerts, festivals, performances) for an artist, filtered by `status` (`current` or `past`). 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. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj` (required)** `array` **Items:** - **`city`** `object | null` - **`id`** `integer | null` - **`name`** `string | null` - **`code2`** `string | null` - **`currency`** `string | null` - **`end_date`** `object` - **`event_name`** `string | null` - **`high_price`** `object` - **`id`** `integer | null` - **`image_url`** `string | null` - **`is_headliner`** `boolean | null` - **`jambase_event_url`** `string | null` - **`low_price`** `object` - **`price`** `object` - **`price_trend`** `array | null` - **`seatgeek_event_url`** `string | null` - **`songkick_event_url`** `string | null` - **`start_date`** `object` - **`ticketmaster_event_url`** `string | null` - **`type`** `string | null` - **`venue_capacity`** `integer | null` - **`venue_id`** `integer | null` - **`venue_name`** `string | null` - **`venue_url`** `string | null` **Example:** ```json { "obj": [ { "id": null, "event_name": null, "jambase_event_url": null, "songkick_event_url": null, "seatgeek_event_url": null, "ticketmaster_event_url": null, "image_url": null, "type": null, "start_date": "", "end_date": "", "venue_id": null, "venue_name": null, "venue_url": null, "venue_capacity": null, "city": { "id": null, "name": null }, "code2": null, "low_price": 1, "high_price": 1, "price": 1, "price_trend": [ { "date": "", "price": 1 } ], "currency": null, "is_headliner": null } ] } ``` ### News - **Method:** `GET` - **Path:** `/api/artist/{id}/news` - **Tags:** Artist 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 `ARTIST_NEWS_DAYS_AGO` 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). #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj` (required)** `array` **Items:** - **`formattedDate`** `object` - **`group_size`** `object` - **`id`** `object` - **`imageUrl`** `string | null` - **`metadata`** `object | null` - **`stars`** `integer | null` - **`subType`** `string | null` - **`summaryData`** `object | null` - **`summaryTemplate`** `string | null` - **`type`** `string | null` **Example:** ```json { "obj": [ { "id": 0, "type": null, "subType": null, "formattedDate": "", "imageUrl": null, "summaryTemplate": null, "summaryData": {}, "metadata": {}, "stars": null, "group_size": null } ] } ``` ### Venues - **Method:** `GET` - **Path:** `/api/artist/{id}/venues` - **Tags:** Artist 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. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj` (required)** `array` **Items:** - **`city`** `object | null` - **`id`** `integer | null` - **`name`** `string | null` - **`code2`** `string | null` - **`events`** `array | null` - **`venue_capacity`** `integer | null` - **`venue_id`** `integer | null` - **`venue_name`** `string | null` - **`venue_url`** `string | null` **Example:** ```json { "obj": [ { "venue_id": null, "venue_name": null, "venue_url": null, "venue_capacity": null, "city": { "id": null, "name": null }, "code2": null, "events": [ { "id": null, "event_name": null, "jambase_event_url": null, "songkick_event_url": null, "seatgeek_event_url": null, "type": null, "start_date": "", "end_date": "", "is_headliner": null } ] } ] } ``` ### Similar Artists by Configurations - **Method:** `GET` - **Path:** `/api/artist/{id}/similar-artists/by-configurations` - **Tags:** Artist Similar artists ranked by weighted embedding configurations (`audience`, `mood`, `genre`, `musicality`). Query must include at least one configuration. The target artist is pinned first in `data`. Pass `segmentSize` to switch to a segmented shape (`by_stage` / `by_health`) instead of a flat list. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj`** `object` **Example:** ```json { "obj": { "data": [ { "id": null, "name": null, "image_url": null, "code2": null, "verified": null, "gender": null, "band": null, "genres": [], "subgenres": [], "primary_genre_smart": {}, "continent": null, "rank": null, "score": 1, "similarity": 1, "career_stage": null, "recent_momentum": null, "network_strength": null, "label": 0, "rank_stats_monthly": [], "rank_diff_monthly": 1, "date_of_birth": "", "normalizedScores": {} } ], "total": 1, "mainArtistNormalizedScores": {} } } ``` ### Artist Cached Stats & Trends - **Method:** `GET` - **Path:** `/api/artist/{id}/cmStats` - **Tags:** Artist 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`. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj`** `object` - **`bimonthly_diff`** `object | null` - **`bimonthly_diff_percent`** `object | null` - **`latest`** `object | null` - **`monthly_diff`** `object | null` - **`monthly_diff_percent`** `object | null` - **`timestamp`** `object` - **`weekly_diff`** `object | null` - **`weekly_diff_percent`** `object | null` **Example:** ```json { "obj": { "timestamp": "", "latest": {}, "weekly_diff": {}, "weekly_diff_percent": {}, "monthly_diff": {}, "monthly_diff_percent": {}, "bimonthly_diff": {}, "bimonthly_diff_percent": {} } } ``` ### List Brand Names - **Method:** `GET` - **Path:** `/api/brand/list` - **Tags:** Brand List all Chartmetric brand IDs and names. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj` (required)** `array` **Items:** - **`id` (required)** `integer` - **`name` (required)** `string` **Example:** ```json { "obj": [ { "id": 0, "name": "" } ] } ``` ### List Brands by Interest Category - **Method:** `GET` - **Path:** `/api/brand/list/by/interest` - **Tags:** Brand 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. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj`** `object` **Example:** ```json { "obj": { "additionalProperty": [ { "brand_id": 0, "brand_name": null, "interest_id": 0, "interest_name": null, "followers": null, "artist_count": null } ] } } ``` ### Get Brand Info - **Method:** `GET` - **Path:** `/api/brand/{brandId}` - **Tags:** Brand 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`. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj`** `object` - **`artists` (required)** `array` **Items:** - **`genres` (required)** `array` **Items:** `string` - **`id` (required)** `object` - **`code2`** `string | null` - **`image_url`** `string | null` - **`instagram_followers`** `object` - **`affinity`** `number | null`, format: `float` - **`overlap`** `integer | null` - **`overlap_percent`** `number | null`, format: `float` - **`total`** `integer | null` - **`instagram_likers`** `object` - **`affinity`** `number | null`, format: `float` - **`average`** `integer | null` - **`overlap`** `integer | null` - **`overlap_percent`** `number | null`, format: `float` - **`name`** `string | null` - **`total` (required)** `integer` - **`brandName`** `string | null` **Example:** ```json { "obj": { "brandName": null, "total": 0, "artists": [ { "id": "", "code2": null, "name": null, "genres": [ "" ], "image_url": null, "instagram_followers": { "total": null, "overlap": null, "overlap_percent": null, "affinity": null }, "instagram_likers": { "average": null, "overlap": null, "overlap_percent": null, "affinity": null } } ] } } ``` ### Get Chartmetric Score - **Method:** `GET` - **Path:** `/api/charts/{byType}/{id}/{chartType}/cm-score` - **Tags:** Charts Chartmetric Score reflects the overall trend for tracks or albums, computed from weighted chart-rank positions across countries over time. Supported `byType` values include `artist`, `track`, `album` depending on `chartType`. Supported `chartType` values include `spotify`, `spotify-album`, `youtube`, `soundcloud`, `tiktok`, `shazam`, `itunes`, `deezer`, `applemusic`, `applemusic-album`. Response carries two parallel views of the score timeline: `overall` (aggregate) and `individual` (per-track/per-album). #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj`** `object` - **`individual` (required)** `array` **Items:** - **`data`** `array | null` - **`id`** `integer | null` - **`name`** `string | null` - **`overall` (required)** `array` **Items:** - **`count`** `integer | null` - **`details`** `array | null` - **`x`** `string | null` - **`y`** `number | null`, format: `float` **Example:** ```json { "obj": { "overall": [ { "x": null, "y": null, "count": null, "details": [ { "trackName": null, "trackId": null, "details": [ { "rank": null, "country": null, "score": null, "genre": null } ] } ] } ], "individual": [ { "id": null, "name": null, "data": [ { "timestp": null, "score": null, "rank_details": [ { "rank": null, "country": null, "score": null, "genre": null } ] } ] } ] } } ``` ### Get Spotify Track Charts - **Method:** `GET` - **Path:** `/api/charts/spotify` - **Tags:** Charts 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. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj`** `object` - **`data` (required)** `array` **Items:** - **`added_at`** `string | null`, format: `date-time` - **`album_ids`** `array | null` - **`album_label`** `array | null` - **`album_names`** `array | null` - **`album_upc`** `array | null` - **`artist_covers`** `array | null` - **`artist_images`** `array | null` - **`artist_names`** `array | null` - **`chart_name`** `string | null` - **`chart_type`** `string | null` - **`cm_artist`** `array | null` - **`cm_track`** `integer | null` - **`code2`** `string | null` - **`code2s`** `array | null` - **`composer_name`** `string | null` - **`country`** `string | null` - **`current_plays`** `integer | null` - **`duration`** `string | null` - **`genre`** `string | null` - **`id`** `integer | null` - **`image_url`** `string | null` - **`isrc`** `string | null` - **`itunes`** `integer | null` - **`itunes_album_ids`** `array | null` - **`itunes_artist_ids`** `array | null` - **`itunes_artist_names`** `array | null` - **`itunes_track_ids`** `array | null` - **`name`** `string | null` - **`peak_date`** `string | null`, format: `date-time` - **`peak_rank`** `integer | null` - **`pre_rank`** `integer | null` - **`rank`** `integer | null` - **`rank_1d_change`** `integer | null` - **`rank_7d_change`** `integer | null` - **`rankStats`** `array | null` - **`release_dates`** `array | null` - **`spotify`** `integer | null` - **`spotify_album_id`** `string | null` - **`spotify_album_ids`** `array | null` - **`spotify_artist_ids`** `array | null` - **`spotify_artist_names`** `array | null` - **`spotify_duration_ms`** `integer | null` - **`spotify_popularity`** `integer | null` - **`spotify_track_ids`** `array | null` - **`storefronts`** `array | null` - **`time_on_chart`** `object` - **`timestp`** `string | null`, format: `date-time` - **`track_genre`** `object` - **`velocity`** `number | null`, format: `float` - **`length` (required)** `integer` **Example:** ```json { "obj": { "length": 0, "data": [ { "rank": null, "pre_rank": null, "peak_rank": null, "peak_date": null, "rank_1d_change": null, "rank_7d_change": null, "chart_name": null, "chart_type": null, "code2": null, "timestp": null, "duration": null, "added_at": null, "velocity": null, "time_on_chart": "", "country": null, "genre": null, "spotify": null, "itunes": null, "current_plays": null, "rankStats": [ { "timestp": null, "rank": null } ], "id": null, "name": null, "isrc": null, "image_url": null, "cm_track": null, "track_genre": "", "spotify_popularity": null, "spotify_duration_ms": null, "spotify_album_id": null, "composer_name": null, "cm_artist": [ 0 ], "artist_names": [ null ], "code2s": [ null ], "artist_images": [ null ], "artist_covers": [ null ], "spotify_artist_ids": [ 1 ], "spotify_artist_names": [ null ], "spotify_track_ids": [ null ], "spotify_album_ids": [ null ], "itunes_artist_ids": [ 1 ], "itunes_artist_names": [ null ], "itunes_track_ids": [ null ], "itunes_album_ids": [ null ], "storefronts": [ null ], "album_ids": [ null ], "album_names": [ null ], "album_upc": [ null ], "album_label": [ null ], "release_dates": [ null ] } ] } } ``` ### Get Spotify Artist Charts - **Method:** `GET` - **Path:** `/api/charts/spotify/artists` - **Tags:** Charts 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. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj`** `object` - **`data` (required)** `array` **Items:** - **`amazon_artist_ids`** `array | null` - **`change`** `integer | null` - **`cm_artist_rank`** `integer | null` - **`cm_artist_score`** `number | null`, format: `float` - **`code2`** `string | null` - **`current_city`** `string | null` - **`deezer_artist_ids`** `array | null` - **`deezer_fans`** `integer | null` - **`hometown_city`** `string | null` - **`id`** `integer | null` - **`image_url`** `string | null` - **`isni`** `string | null` - **`itunes_artist_ids`** `array | null` - **`monthly_playlist_reach`** `integer | null` - **`name`** `string | null` - **`peak_date`** `string | null`, format: `date-time` - **`peak_rank`** `integer | null` - **`rank`** `integer | null` - **`rankStats`** `array | null` - **`sp_followers`** `integer | null` - **`sp_monthly_listeners`** `integer | null` - **`sp_popularity`** `integer | null` - **`spotify_artist_ids`** `array | null` - **`streak`** `integer | null` - **`tags`** `array | null` - **`time_on_chart`** `object` - **`timestp`** `string | null`, format: `date-time` - **`length` (required)** `integer` **Example:** ```json { "obj": { "length": 0, "data": [ { "id": null, "name": null, "image_url": null, "isni": null, "code2": null, "hometown_city": null, "current_city": null, "sp_followers": null, "sp_popularity": null, "sp_monthly_listeners": null, "deezer_fans": null, "tags": [], "spotify_artist_ids": [ 1 ], "itunes_artist_ids": [ 1 ], "deezer_artist_ids": [ 1 ], "amazon_artist_ids": [ 1 ], "cm_artist_rank": null, "cm_artist_score": null, "timestp": null, "monthly_playlist_reach": null, "rank": null, "change": null, "streak": null, "peak_date": null, "peak_rank": null, "time_on_chart": 1, "rankStats": [ { "date": null, "rank": 1 } ] } ] } } ``` ### Get Spotify Fresh Finds Charts - **Method:** `GET` - **Path:** `/api/charts/spotify/freshfind` - **Tags:** Charts 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 }`). #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj` (required)** `array` **Items:** - **`album_ids`** `array | null` - **`album_label`** `array | null` - **`album_names`** `array | null` - **`album_upc`** `array | null` - **`artist_covers`** `array | null` - **`artist_images`** `array | null` - **`artist_names`** `array | null` - **`artists`** `object` - **`cm_artist`** `array | null` - **`cm_track`** `integer | null` - **`code2s`** `array | null` - **`composer_name`** `string | null` - **`fresh_finds_playlists`** `array | null` - **`fresh_finds_playlists_ids`** `array | null` - **`id`** `integer | null` - **`image_url`** `string | null` - **`isrc`** `string | null` - **`itunes_album_ids`** `array | null` - **`itunes_artist_ids`** `array | null` - **`itunes_artist_names`** `array | null` - **`itunes_track_ids`** `array | null` - **`name`** `string | null` - **`num_all_playlists`** `integer | null` - **`num_ff_playlists`** `integer | null` - **`rank`** `integer | null` - **`release_dates`** `array | null` - **`spotify_album_id`** `string | null` - **`spotify_album_ids`** `array | null` - **`spotify_artist_ids`** `array | null` - **`spotify_artist_names`** `array | null` - **`spotify_duration_ms`** `integer | null` - **`spotify_popularity`** `integer | null` - **`spotify_track_id`** `string | null` - **`spotify_track_ids`** `array | null` - **`storefronts`** `array | null` - **`track_genre`** `object` **Example:** ```json { "obj": [ { "spotify_track_id": null, "rank": null, "num_all_playlists": null, "num_ff_playlists": null, "fresh_finds_playlists_ids": [ 1 ], "fresh_finds_playlists": [ "" ], "artists": { "id": null, "name": null, "code2": null, "image_url": null, "career_health": null, "career_stage": null, "network_strength": {} }, "id": null, "name": null, "isrc": null, "image_url": null, "cm_track": null, "track_genre": "", "spotify_popularity": null, "spotify_duration_ms": null, "spotify_album_id": null, "composer_name": null, "cm_artist": [ 0 ], "artist_names": [ null ], "code2s": [ null ], "artist_images": [ null ], "artist_covers": [ null ], "spotify_artist_ids": [ 1 ], "spotify_artist_names": [ null ], "spotify_track_ids": [ null ], "spotify_album_ids": [ null ], "itunes_artist_ids": [ 1 ], "itunes_artist_names": [ null ], "itunes_track_ids": [ null ], "itunes_album_ids": [ null ], "storefronts": [ null ], "album_ids": [ null ], "album_names": [ null ], "album_upc": [ null ], "album_label": [ null ], "release_dates": [ null ] } ] } ``` ### Get Deezer Top-Track Chart - **Method:** `GET` - **Path:** `/api/charts/deezer` - **Tags:** Charts 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. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj` (required)** `object` - **`data` (required)** `array` **Items:** - **`added_at`** `string | null`, format: `date-time` - **`album`** `object` - **`album_ids`** `array | null` - **`album_label`** `array | null` - **`album_names`** `array | null` - **`album_upc`** `array | null` - **`artist_covers`** `array | null` - **`artist_images`** `array | null` - **`artist_names`** `array | null` - **`artists`** `array | null` - **`cm_artist`** `object` - **`cm_track`** `integer | null` - **`code2`** `string | null` - **`code2s`** `array | null` - **`deezer`** `integer | null` - **`deezer_album`** `object` - **`deezer_album_ids`** `array | null` - **`deezer_artist_ids`** `array | null` - **`deezer_artist_names`** `array | null` - **`deezer_track_ids`** `array | null` - **`duration_ms`** `integer | null` - **`explicit`** `boolean | null` - **`id`** `object` - **`image_url`** `string | null` - **`isrc`** `string | null` - **`name`** `string | null` - **`peak_date`** `string | null`, format: `date-time` - **`peak_rank`** `integer | null` - **`pre_rank`** `integer | null` - **`preview_url`** `string | null` - **`rank`** `integer | null` - **`rankStats`** `array | null` - **`release_dates`** `array | null` - **`spotify_popularity`** `integer | null` - **`time_on_chart`** `object` - **`track_genre`** `object` - **`velocity`** `number | null`, format: `float` - **`length` (required)** `integer` **Example:** ```json { "obj": { "length": 0, "data": [ { "id": 1, "deezer": null, "deezer_album": {}, "deezer_artist_names": [ null ], "deezer_artist_ids": [ null ], "deezer_track_ids": [ null ], "deezer_album_ids": [ null ], "rank": null, "added_at": null, "code2": null, "velocity": null, "pre_rank": null, "peak_rank": null, "peak_date": null, "time_on_chart": 1, "rankStats": [ { "rank": null, "timestp": null } ], "cm_track": null, "name": null, "isrc": null, "image_url": null, "cm_artist": 1, "artist_names": [ null ], "code2s": [ null ], "artist_images": [ null ], "artist_covers": [ null ], "album_ids": [ null ], "album_names": [ null ], "album_upc": [ null ], "album_label": [ null ], "release_dates": [ null ], "artists": [ { "id": null, "name": null, "code2": null, "image_url": null, "career_stage": null } ], "album": [ {} ], "duration_ms": null, "explicit": null, "preview_url": null, "track_genre": "", "spotify_popularity": null } ] } } ``` ### QQ Music Charts - **Method:** `GET` - **Path:** `/api/charts/qq` - **Tags:** Charts 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`. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj`** `object` - **`data`** `array | null` - **`length`** `integer | null` **Example:** ```json { "obj": { "length": null, "data": [ { "id": 0, "name": null, "isrc": null, "image_url": null, "description": null, "tags": null, "cm_track": null, "cm_artist": [ null ], "artist_names": [ null ], "code2s": [ null ], "artist_images": [ null ], "artist_covers": [ null ], "spotify_track_ids": [ null ], "spotify_album_ids": [ null ], "spotify_duration_ms": null, "itunes_track_ids": [ null ], "itunes_album_ids": [ null ], "itunes_artist_ids": [ 1 ], "itunes_artist_names": [ null ], "storefronts": [ null ], "deezer_track_ids": [ null ], "deezer_album_ids": [ 1 ], "deezer_duration": null, "amazon_track_ids": [ null ], "amazon_album_ids": [ null ], "album_ids": [ 0 ], "album_names": [ null ], "album_upc": [ null ], "album_label": [ null ], "release_dates": [ "" ], "created_at": "", "modified_at": "", "rank": null, "pre_rank": null, "peak_rank": null, "peak_date": "", "added_at": "", "velocity": null, "time_on_chart": "", "qq": "", "rankStats": [ { "rank": null, "timestp": "" } ] } ] } } ``` ### Amazon Track Charts - **Method:** `GET` - **Path:** `/api/charts/amazon/tracks` - **Tags:** Charts 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`. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj`** `object` - **`data`** `array | null` - **`length`** `integer | null` **Example:** ```json { "obj": { "length": null, "data": [ { "id": 0, "name": null, "isrc": null, "image_url": null, "description": null, "tags": null, "cm_track": null, "cm_artist": [ null ], "artist_names": [ null ], "code2s": [ null ], "artist_images": [ null ], "artist_covers": [ null ], "spotify_track_ids": [ null ], "spotify_album_ids": [ null ], "spotify_duration_ms": null, "itunes_track_ids": [ null ], "itunes_album_ids": [ null ], "itunes_artist_ids": [ 1 ], "itunes_artist_names": [ null ], "storefronts": [ null ], "deezer_track_ids": [ null ], "deezer_album_ids": [ 1 ], "deezer_duration": null, "amazon_track_ids": [ null ], "amazon_album_ids": [ null ], "album_ids": [ 0 ], "album_names": [ null ], "album_upc": [ null ], "album_label": [ null ], "release_dates": [ "" ], "created_at": "", "modified_at": "", "rank_1d_change": null, "rank_7d_change": null, "chart_name": null, "chart_type": null, "code2": null, "timestp": null, "duration": null, "rank": null, "pre_rank": null, "peak_rank": null, "peak_date": "", "time_on_chart": "", "added_at": "", "velocity": null, "amazon": null, "amazon_browse": null, "amazon_artist_id": null, "amazon_artist_ids": [ null ], "amazon_album_id": null, "amazon_genres": [ null ], "amazon_artist_names": [ null ], "rankStats": [ { "rank": null, "timestp": "" } ] } ] } } ``` ### Amazon Album Charts - **Method:** `GET` - **Path:** `/api/charts/amazon/albums` - **Tags:** Charts 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`. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj`** `object` - **`data`** `array | null` - **`length`** `integer | null` **Example:** ```json { "obj": { "length": null, "data": [ { "rank": null, "pre_rank": null, "peak_rank": null, "peak_date": "", "added_at": "", "velocity": null, "time_on_chart": "", "amazon_album": "", "original_id": null, "code2": null, "genre": null, "id": 0, "name": null, "upc": null, "label": null, "image_url": null, "release_date": "", "cm_album": null, "num_track": "", "amazon_album_ids": [ null ], "artists": [ {} ], "rankStats": [ { "rank": null, "timestp": "" } ] } ] } } ``` ### Get Apple Music Track Charts - **Method:** `GET` - **Path:** `/api/charts/applemusic/tracks` - **Tags:** Charts Return tracks charting on Apple Music for a given date. Supports `type` = `top` / `daily` / `city` (the last requires `city_id`). Entries combine chart position + historical `rankStats` with the track basic info. The `top` S3-backed chart path applies pagination after the fetch. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj`** `object` - **`data` (required)** `array` **Items:** - **`added_at`** `string | null`, format: `date-time` - **`album_ids`** `array | null` - **`album_label`** `array | null` - **`album_names`** `array | null` - **`album_upc`** `array | null` - **`artist_covers`** `array | null` - **`artist_images`** `array | null` - **`artist_names`** `array | null` - **`chart_name`** `string | null` - **`chart_type`** `string | null` - **`cm_artist`** `array | null` - **`cm_track`** `integer | null` - **`code2`** `string | null` - **`code2s`** `array | null` - **`composer_name`** `string | null` - **`country`** `string | null` - **`current_plays`** `integer | null` - **`duration`** `string | null` - **`genre`** `string | null` - **`id`** `integer | null` - **`image_url`** `string | null` - **`isrc`** `string | null` - **`itunes`** `integer | null` - **`itunes_album_ids`** `array | null` - **`itunes_artist_ids`** `array | null` - **`itunes_artist_names`** `array | null` - **`itunes_track_ids`** `array | null` - **`name`** `string | null` - **`peak_date`** `string | null`, format: `date-time` - **`peak_rank`** `integer | null` - **`pre_rank`** `integer | null` - **`rank`** `integer | null` - **`rank_1d_change`** `integer | null` - **`rank_7d_change`** `integer | null` - **`rankStats`** `array | null` - **`release_dates`** `array | null` - **`spotify`** `integer | null` - **`spotify_album_id`** `string | null` - **`spotify_album_ids`** `array | null` - **`spotify_artist_ids`** `array | null` - **`spotify_artist_names`** `array | null` - **`spotify_duration_ms`** `integer | null` - **`spotify_popularity`** `integer | null` - **`spotify_track_ids`** `array | null` - **`storefronts`** `array | null` - **`time_on_chart`** `object` - **`timestp`** `string | null`, format: `date-time` - **`track_genre`** `object` - **`velocity`** `number | null`, format: `float` - **`length` (required)** `integer` **Example:** ```json { "obj": { "length": 0, "data": [ { "rank": null, "pre_rank": null, "peak_rank": null, "peak_date": null, "rank_1d_change": null, "rank_7d_change": null, "chart_name": null, "chart_type": null, "code2": null, "timestp": null, "duration": null, "added_at": null, "velocity": null, "time_on_chart": "", "country": null, "genre": null, "spotify": null, "itunes": null, "current_plays": null, "rankStats": [ { "timestp": null, "rank": null } ], "id": null, "name": null, "isrc": null, "image_url": null, "cm_track": null, "track_genre": "", "spotify_popularity": null, "spotify_duration_ms": null, "spotify_album_id": null, "composer_name": null, "cm_artist": [ 0 ], "artist_names": [ null ], "code2s": [ null ], "artist_images": [ null ], "artist_covers": [ null ], "spotify_artist_ids": [ 1 ], "spotify_artist_names": [ null ], "spotify_track_ids": [ null ], "spotify_album_ids": [ null ], "itunes_artist_ids": [ 1 ], "itunes_artist_names": [ null ], "itunes_track_ids": [ null ], "itunes_album_ids": [ null ], "storefronts": [ null ], "album_ids": [ null ], "album_names": [ null ], "album_upc": [ null ], "album_label": [ null ], "release_dates": [ null ] } ] } } ``` ### Get Apple Music Album Charts - **Method:** `GET` - **Path:** `/api/charts/applemusic/albums` - **Tags:** Charts 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. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj`** `object` - **`data` (required)** `array` **Items:** - **`added_at`** `string | null`, format: `date-time` - **`artist_names`** `array | null` - **`chart_name`** `string | null` - **`chart_type`** `string | null` - **`cm_album`** `integer | null` - **`cm_artist`** `array | null` - **`code2`** `string | null` - **`country`** `string | null` - **`duration`** `string | null` - **`genre`** `string | null` - **`id`** `integer | null` - **`image_url`** `string | null` - **`itunes`** `integer | null` - **`itunes_album_id`** `object` - **`itunes_artist_ids`** `array | null` - **`itunes_artist_names`** `array | null` - **`label`** `string | null` - **`name`** `string | null` - **`peak_date`** `string | null`, format: `date-time` - **`peak_rank`** `integer | null` - **`pre_rank`** `integer | null` - **`rank`** `integer | null` - **`rank_1d_change`** `integer | null` - **`rank_7d_change`** `integer | null` - **`rankStats`** `array | null` - **`release_date`** `string | null`, format: `date-time` - **`storefronts`** `array | null` - **`time_on_chart`** `object` - **`timestp`** `string | null`, format: `date-time` - **`upc`** `string | null` - **`velocity`** `number | null`, format: `float` - **`length` (required)** `integer` **Example:** ```json { "obj": { "length": 0, "data": [ { "rank": null, "pre_rank": null, "peak_rank": null, "peak_date": null, "rank_1d_change": null, "rank_7d_change": null, "chart_name": null, "chart_type": null, "code2": null, "timestp": null, "duration": null, "id": null, "name": null, "image_url": null, "upc": null, "release_date": null, "label": null, "genre": null, "added_at": null, "country": null, "itunes": null, "itunes_album_id": "", "cm_album": null, "cm_artist": [ 0 ], "artist_names": [ null ], "itunes_artist_ids": [ null ], "itunes_artist_names": [ null ], "storefronts": [ null ], "velocity": null, "time_on_chart": "", "rankStats": [ { "timestp": null, "rank": null } ] } ] } } ``` ### Get Apple Music Video Charts - **Method:** `GET` - **Path:** `/api/charts/applemusic/videos` - **Tags:** Charts 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. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj`** `object` - **`data` (required)** `array` **Items:** - **`added_at`** `string | null`, format: `date-time` - **`album_ids`** `array | null` - **`album_label`** `array | null` - **`album_names`** `array | null` - **`album_upc`** `array | null` - **`artist_covers`** `array | null` - **`artist_images`** `array | null` - **`artist_names`** `array | null` - **`chart_name`** `string | null` - **`chart_type`** `string | null` - **`cm_artist`** `array | null` - **`cm_track`** `integer | null` - **`code2`** `string | null` - **`code2s`** `array | null` - **`composer_name`** `string | null` - **`country`** `string | null` - **`current_plays`** `integer | null` - **`duration`** `string | null` - **`genre`** `string | null` - **`id`** `integer | null` - **`image_url`** `string | null` - **`isrc`** `string | null` - **`itunes`** `integer | null` - **`itunes_album_ids`** `array | null` - **`itunes_artist_ids`** `array | null` - **`itunes_artist_names`** `array | null` - **`itunes_track_ids`** `array | null` - **`name`** `string | null` - **`peak_date`** `string | null`, format: `date-time` - **`peak_rank`** `integer | null` - **`pre_rank`** `integer | null` - **`rank`** `integer | null` - **`rank_1d_change`** `integer | null` - **`rank_7d_change`** `integer | null` - **`rankStats`** `array | null` - **`release_dates`** `array | null` - **`spotify`** `integer | null` - **`spotify_album_id`** `string | null` - **`spotify_album_ids`** `array | null` - **`spotify_artist_ids`** `array | null` - **`spotify_artist_names`** `array | null` - **`spotify_duration_ms`** `integer | null` - **`spotify_popularity`** `integer | null` - **`spotify_track_ids`** `array | null` - **`storefronts`** `array | null` - **`time_on_chart`** `object` - **`timestp`** `string | null`, format: `date-time` - **`track_genre`** `object` - **`velocity`** `number | null`, format: `float` - **`length` (required)** `integer` **Example:** ```json { "obj": { "length": 0, "data": [ { "rank": null, "pre_rank": null, "peak_rank": null, "peak_date": null, "rank_1d_change": null, "rank_7d_change": null, "chart_name": null, "chart_type": null, "code2": null, "timestp": null, "duration": null, "added_at": null, "velocity": null, "time_on_chart": "", "country": null, "genre": null, "spotify": null, "itunes": null, "current_plays": null, "rankStats": [ { "timestp": null, "rank": null } ], "id": null, "name": null, "isrc": null, "image_url": null, "cm_track": null, "track_genre": "", "spotify_popularity": null, "spotify_duration_ms": null, "spotify_album_id": null, "composer_name": null, "cm_artist": [ 0 ], "artist_names": [ null ], "code2s": [ null ], "artist_images": [ null ], "artist_covers": [ null ], "spotify_artist_ids": [ 1 ], "spotify_artist_names": [ null ], "spotify_track_ids": [ null ], "spotify_album_ids": [ null ], "itunes_artist_ids": [ 1 ], "itunes_artist_names": [ null ], "itunes_track_ids": [ null ], "itunes_album_ids": [ null ], "storefronts": [ null ], "album_ids": [ null ], "album_names": [ null ], "album_upc": [ null ], "album_label": [ null ], "release_dates": [ null ] } ] } } ``` ### Get iTunes Track Charts - **Method:** `GET` - **Path:** `/api/charts/itunes/tracks` - **Tags:** Charts 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. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj`** `object` - **`data` (required)** `array` **Items:** - **`added_at`** `string | null`, format: `date-time` - **`album_ids`** `array | null` - **`album_label`** `array | null` - **`album_names`** `array | null` - **`album_upc`** `array | null` - **`artist_covers`** `array | null` - **`artist_images`** `array | null` - **`artist_names`** `array | null` - **`chart_name`** `string | null` - **`chart_type`** `string | null` - **`cm_artist`** `array | null` - **`cm_track`** `integer | null` - **`code2`** `string | null` - **`code2s`** `array | null` - **`composer_name`** `string | null` - **`country`** `string | null` - **`current_plays`** `integer | null` - **`duration`** `string | null` - **`genre`** `string | null` - **`id`** `integer | null` - **`image_url`** `string | null` - **`isrc`** `string | null` - **`itunes`** `integer | null` - **`itunes_album_ids`** `array | null` - **`itunes_artist_ids`** `array | null` - **`itunes_artist_names`** `array | null` - **`itunes_track_ids`** `array | null` - **`name`** `string | null` - **`peak_date`** `string | null`, format: `date-time` - **`peak_rank`** `integer | null` - **`pre_rank`** `integer | null` - **`rank`** `integer | null` - **`rank_1d_change`** `integer | null` - **`rank_7d_change`** `integer | null` - **`rankStats`** `array | null` - **`release_dates`** `array | null` - **`spotify`** `integer | null` - **`spotify_album_id`** `string | null` - **`spotify_album_ids`** `array | null` - **`spotify_artist_ids`** `array | null` - **`spotify_artist_names`** `array | null` - **`spotify_duration_ms`** `integer | null` - **`spotify_popularity`** `integer | null` - **`spotify_track_ids`** `array | null` - **`storefronts`** `array | null` - **`time_on_chart`** `object` - **`timestp`** `string | null`, format: `date-time` - **`track_genre`** `object` - **`velocity`** `number | null`, format: `float` - **`length` (required)** `integer` **Example:** ```json { "obj": { "length": 0, "data": [ { "rank": null, "pre_rank": null, "peak_rank": null, "peak_date": null, "rank_1d_change": null, "rank_7d_change": null, "chart_name": null, "chart_type": null, "code2": null, "timestp": null, "duration": null, "added_at": null, "velocity": null, "time_on_chart": "", "country": null, "genre": null, "spotify": null, "itunes": null, "current_plays": null, "rankStats": [ { "timestp": null, "rank": null } ], "id": null, "name": null, "isrc": null, "image_url": null, "cm_track": null, "track_genre": "", "spotify_popularity": null, "spotify_duration_ms": null, "spotify_album_id": null, "composer_name": null, "cm_artist": [ 0 ], "artist_names": [ null ], "code2s": [ null ], "artist_images": [ null ], "artist_covers": [ null ], "spotify_artist_ids": [ 1 ], "spotify_artist_names": [ null ], "spotify_track_ids": [ null ], "spotify_album_ids": [ null ], "itunes_artist_ids": [ 1 ], "itunes_artist_names": [ null ], "itunes_track_ids": [ null ], "itunes_album_ids": [ null ], "storefronts": [ null ], "album_ids": [ null ], "album_names": [ null ], "album_upc": [ null ], "album_label": [ null ], "release_dates": [ null ] } ] } } ``` ### Get iTunes Album Charts - **Method:** `GET` - **Path:** `/api/charts/itunes/albums` - **Tags:** Charts Return albums charting on iTunes for a given date, filterable by country and genre. Entries carry album metadata + chart position + `rankStats`. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj`** `object` - **`data` (required)** `array` **Items:** - **`added_at`** `string | null`, format: `date-time` - **`artist_names`** `array | null` - **`chart_name`** `string | null` - **`chart_type`** `string | null` - **`cm_album`** `integer | null` - **`cm_artist`** `array | null` - **`code2`** `string | null` - **`country`** `string | null` - **`duration`** `string | null` - **`genre`** `string | null` - **`id`** `integer | null` - **`image_url`** `string | null` - **`itunes`** `integer | null` - **`itunes_album_id`** `object` - **`itunes_artist_ids`** `array | null` - **`itunes_artist_names`** `array | null` - **`label`** `string | null` - **`name`** `string | null` - **`peak_date`** `string | null`, format: `date-time` - **`peak_rank`** `integer | null` - **`pre_rank`** `integer | null` - **`rank`** `integer | null` - **`rank_1d_change`** `integer | null` - **`rank_7d_change`** `integer | null` - **`rankStats`** `array | null` - **`release_date`** `string | null`, format: `date-time` - **`storefronts`** `array | null` - **`time_on_chart`** `object` - **`timestp`** `string | null`, format: `date-time` - **`upc`** `string | null` - **`velocity`** `number | null`, format: `float` - **`length` (required)** `integer` **Example:** ```json { "obj": { "length": 0, "data": [ { "rank": null, "pre_rank": null, "peak_rank": null, "peak_date": null, "rank_1d_change": null, "rank_7d_change": null, "chart_name": null, "chart_type": null, "code2": null, "timestp": null, "duration": null, "id": null, "name": null, "image_url": null, "upc": null, "release_date": null, "label": null, "genre": null, "added_at": null, "country": null, "itunes": null, "itunes_album_id": "", "cm_album": null, "cm_artist": [ 0 ], "artist_names": [ null ], "itunes_artist_ids": [ null ], "itunes_artist_names": [ null ], "storefronts": [ null ], "velocity": null, "time_on_chart": "", "rankStats": [ { "timestp": null, "rank": null } ] } ] } } ``` ### Get iTunes Video Charts - **Method:** `GET` - **Path:** `/api/charts/itunes/videos` - **Tags:** Charts Return music videos charting on iTunes for a given date. Genre is fixed to `Music Videos` by the handler — the `genre` query param from the apidoc is ignored. Shape mirrors the iTunes track chart. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj`** `object` - **`data` (required)** `array` **Items:** - **`added_at`** `string | null`, format: `date-time` - **`album_ids`** `array | null` - **`album_label`** `array | null` - **`album_names`** `array | null` - **`album_upc`** `array | null` - **`artist_covers`** `array | null` - **`artist_images`** `array | null` - **`artist_names`** `array | null` - **`chart_name`** `string | null` - **`chart_type`** `string | null` - **`cm_artist`** `array | null` - **`cm_track`** `integer | null` - **`code2`** `string | null` - **`code2s`** `array | null` - **`composer_name`** `string | null` - **`country`** `string | null` - **`current_plays`** `integer | null` - **`duration`** `string | null` - **`genre`** `string | null` - **`id`** `integer | null` - **`image_url`** `string | null` - **`isrc`** `string | null` - **`itunes`** `integer | null` - **`itunes_album_ids`** `array | null` - **`itunes_artist_ids`** `array | null` - **`itunes_artist_names`** `array | null` - **`itunes_track_ids`** `array | null` - **`name`** `string | null` - **`peak_date`** `string | null`, format: `date-time` - **`peak_rank`** `integer | null` - **`pre_rank`** `integer | null` - **`rank`** `integer | null` - **`rank_1d_change`** `integer | null` - **`rank_7d_change`** `integer | null` - **`rankStats`** `array | null` - **`release_dates`** `array | null` - **`spotify`** `integer | null` - **`spotify_album_id`** `string | null` - **`spotify_album_ids`** `array | null` - **`spotify_artist_ids`** `array | null` - **`spotify_artist_names`** `array | null` - **`spotify_duration_ms`** `integer | null` - **`spotify_popularity`** `integer | null` - **`spotify_track_ids`** `array | null` - **`storefronts`** `array | null` - **`time_on_chart`** `object` - **`timestp`** `string | null`, format: `date-time` - **`track_genre`** `object` - **`velocity`** `number | null`, format: `float` - **`length` (required)** `integer` **Example:** ```json { "obj": { "length": 0, "data": [ { "rank": null, "pre_rank": null, "peak_rank": null, "peak_date": null, "rank_1d_change": null, "rank_7d_change": null, "chart_name": null, "chart_type": null, "code2": null, "timestp": null, "duration": null, "added_at": null, "velocity": null, "time_on_chart": "", "country": null, "genre": null, "spotify": null, "itunes": null, "current_plays": null, "rankStats": [ { "timestp": null, "rank": null } ], "id": null, "name": null, "isrc": null, "image_url": null, "cm_track": null, "track_genre": "", "spotify_popularity": null, "spotify_duration_ms": null, "spotify_album_id": null, "composer_name": null, "cm_artist": [ 0 ], "artist_names": [ null ], "code2s": [ null ], "artist_images": [ null ], "artist_covers": [ null ], "spotify_artist_ids": [ 1 ], "spotify_artist_names": [ null ], "spotify_track_ids": [ null ], "spotify_album_ids": [ null ], "itunes_artist_ids": [ 1 ], "itunes_artist_names": [ null ], "itunes_track_ids": [ null ], "itunes_album_ids": [ null ], "storefronts": [ null ], "album_ids": [ null ], "album_names": [ null ], "album_upc": [ null ], "album_label": [ null ], "release_dates": [ null ] } ] } } ``` ### Shazam Track Charts - **Method:** `GET` - **Path:** `/api/charts/shazam` - **Tags:** Charts 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. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj`** `object` - **`data`** `array | null` - **`length`** `integer | null` **Example:** ```json { "obj": { "length": null, "data": [ { "id": 0, "name": null, "isrc": null, "image_url": null, "description": null, "tags": null, "cm_track": null, "cm_artist": [ null ], "artist_names": [ null ], "code2s": [ null ], "artist_images": [ null ], "artist_covers": [ null ], "spotify_track_ids": [ null ], "spotify_album_ids": [ null ], "spotify_duration_ms": null, "itunes_track_ids": [ null ], "itunes_album_ids": [ null ], "itunes_artist_ids": [ 1 ], "itunes_artist_names": [ null ], "storefronts": [ null ], "deezer_track_ids": [ null ], "deezer_album_ids": [ 1 ], "deezer_duration": null, "amazon_track_ids": [ null ], "amazon_album_ids": [ null ], "album_ids": [ 0 ], "album_names": [ null ], "album_upc": [ null ], "album_label": [ null ], "release_dates": [ "" ], "created_at": "", "modified_at": "", "rank": null, "pre_rank": null, "peak_rank": null, "peak_date": "", "added_at": "", "velocity": null, "time_on_chart": "", "code2": null, "city": null, "genre": null, "shazam_track_id": "", "itunes_id": "", "itunes_track_id": null, "itunes_album_id": [ null ], "num_of_shazams": 1, "countries_charting_count": null, "rankStats": [ { "rank": null, "timestp": "" } ] } ] } } ``` ### Shazam Chart Cities - **Method:** `GET` - **Path:** `/api/charts/shazam/{country_code}/cities` - **Tags:** Charts 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). #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj`** `object` - **`cities`** `object` - **`length`** `integer | null` **Example:** ```json { "obj": { "length": null, "cities": [ null ] } } ``` ### SoundCloud Charts (Legacy) - **Method:** `GET` - **Path:** `/api/charts/soundcloud` - **Tags:** Charts 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. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj`** `object` - **`data`** `array | null` - **`length`** `integer | null` **Example:** ```json { "obj": { "length": null, "data": [ { "id": 0, "name": null, "isrc": null, "image_url": null, "description": null, "tags": null, "cm_track": null, "cm_artist": [ null ], "artist_names": [ null ], "code2s": [ null ], "artist_images": [ null ], "artist_covers": [ null ], "spotify_track_ids": [ null ], "spotify_album_ids": [ null ], "spotify_duration_ms": null, "itunes_track_ids": [ null ], "itunes_album_ids": [ null ], "itunes_artist_ids": [ 1 ], "itunes_artist_names": [ null ], "storefronts": [ null ], "deezer_track_ids": [ null ], "deezer_album_ids": [ 1 ], "deezer_duration": null, "amazon_track_ids": [ null ], "amazon_album_ids": [ null ], "album_ids": [ 0 ], "album_names": [ null ], "album_upc": [ null ], "album_label": [ null ], "release_dates": [ "" ], "created_at": "", "modified_at": "", "rank": null, "pre_rank": null, "peak_rank": null, "peak_date": "", "added_at": "", "velocity": null, "time_on_chart": "", "country": null, "genre": null, "kind": null, "soundcloud_track_id": "", "playcount_all": "", "playcount_weekly": "", "artwork_url": null, "permalink_url": null, "public": null, "publisher": null, "writer_composer": null, "artist": null, "album_title": null, "soundcloud_user": {}, "rankStats": [ { "rank": null, "timestp": "" } ] } ] } } ``` ### Beatport Charts - **Method:** `GET` - **Path:** `/api/charts/beatport` - **Tags:** Charts 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`. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj`** `object` - **`data`** `array | null` - **`length`** `integer | null` **Example:** ```json { "obj": { "length": null, "data": [ { "id": 0, "name": null, "isrc": null, "image_url": null, "description": null, "tags": null, "cm_track": null, "cm_artist": [ null ], "artist_names": [ null ], "code2s": [ null ], "artist_images": [ null ], "artist_covers": [ null ], "spotify_track_ids": [ null ], "spotify_album_ids": [ null ], "spotify_duration_ms": null, "itunes_track_ids": [ null ], "itunes_album_ids": [ null ], "itunes_artist_ids": [ 1 ], "itunes_artist_names": [ null ], "storefronts": [ null ], "deezer_track_ids": [ null ], "deezer_album_ids": [ 1 ], "deezer_duration": null, "amazon_track_ids": [ null ], "amazon_album_ids": [ null ], "album_ids": [ 0 ], "album_names": [ null ], "album_upc": [ null ], "album_label": [ null ], "release_dates": [ "" ], "created_at": "", "modified_at": "", "rank": null, "pre_rank": null, "peak_rank": null, "peak_date": "", "added_at": "", "velocity": null, "time_on_chart": "", "genre": null, "beatport": "", "remixers": null, "bc_label": null, "track_name": null, "artist_name": null, "rankStats": [ { "rank": null, "timestp": "" } ] } ] } } ``` ### Get TikTok Top-Track Chart (legacy post/country) - **Method:** `GET` - **Path:** `/api/charts/tiktok/tracks` - **Tags:** Charts 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. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj` (required)** `object` - **`data` (required)** `array` **Items:** - **`added_at`** `string | null`, format: `date-time` - **`album`** `object` - **`album_ids`** `array | null` - **`album_label`** `array | null` - **`album_names`** `array | null` - **`album_upc`** `array | null` - **`artist_covers`** `array | null` - **`artist_images`** `array | null` - **`artist_names`** `array | null` - **`artists`** `array | null` - **`cm_artist`** `object` - **`cm_track`** `integer | null` - **`code2s`** `array | null` - **`daily_posts`** `integer | null` - **`duration_ms`** `integer | null` - **`explicit`** `boolean | null` - **`id`** `integer | null` - **`image_url`** `string | null` - **`isrc`** `string | null` - **`name`** `string | null` - **`peak_date`** `string | null`, format: `date-time` - **`peak_rank`** `integer | null` - **`posts`** `integer | null` - **`pre_rank`** `integer | null` - **`preview_url`** `string | null` - **`rank`** `integer | null` - **`rankStats`** `array | null` - **`release_dates`** `array | null` - **`spotify_popularity`** `integer | null` - **`tiktok`** `integer | null` - **`tiktok_artist_names`** `array | null` - **`tiktok_song_id`** `string | null` - **`tiktok_track_id`** `string | null` - **`tiktok_track_ids`** `array | null` - **`time_on_chart`** `object` - **`track_genre`** `object` - **`velocity`** `number | null`, format: `float` - **`views`** `integer | null` - **`views_prev`** `integer | null` - **`weekly_posts`** `integer | null` - **`length` (required)** `integer` **Example:** ```json { "obj": { "length": 0, "data": [ { "id": null, "tiktok_track_id": null, "tiktok": null, "tiktok_song_id": null, "tiktok_artist_names": [ null ], "tiktok_track_ids": [ null ], "rank": null, "posts": null, "weekly_posts": null, "daily_posts": null, "views": null, "views_prev": null, "added_at": null, "velocity": null, "pre_rank": null, "peak_rank": null, "peak_date": null, "time_on_chart": 1, "rankStats": [ { "rank": null, "posts": null, "views": null, "timestp": null } ], "cm_track": null, "name": null, "isrc": null, "image_url": null, "cm_artist": 1, "artist_names": [ null ], "code2s": [ null ], "artist_images": [ null ], "artist_covers": [ null ], "album_ids": [ null ], "album_names": [ null ], "album_upc": [ null ], "album_label": [ null ], "release_dates": [ null ], "artists": [ { "id": null, "name": null, "code2": null, "image_url": null, "career_stage": null } ], "album": [ {} ], "duration_ms": null, "explicit": null, "preview_url": null, "track_genre": "", "spotify_popularity": null } ] } } ``` ### Get TikTok Top-Video Chart - **Method:** `GET` - **Path:** `/api/charts/tiktok/videos` - **Tags:** Charts 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). #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj` (required)** `object` - **`data` (required)** `array` **Items:** - **`added_at`** `string | null`, format: `date-time` - **`album`** `object` - **`album_ids`** `array | null` - **`album_label`** `array | null` - **`album_names`** `array | null` - **`album_upc`** `array | null` - **`artist_covers`** `array | null` - **`artist_images`** `array | null` - **`artist_names`** `array | null` - **`artists`** `array | null` - **`cm_artist`** `object` - **`cm_track`** `integer | null` - **`code2s`** `array | null` - **`comments`** `integer | null` - **`duration_ms`** `integer | null` - **`explicit`** `boolean | null` - **`id`** `object` - **`image_url`** `string | null` - **`isrc`** `string | null` - **`likes`** `integer | null` - **`name`** `string | null` - **`peak_date`** `string | null`, format: `date-time` - **`peak_rank`** `integer | null` - **`pre_rank`** `integer | null` - **`preview_url`** `string | null` - **`rank`** `integer | null` - **`rankStats`** `array | null` - **`release_dates`** `array | null` - **`spotify_popularity`** `integer | null` - **`tiktok_video`** `object` - **`time_on_chart`** `object` - **`track_genre`** `object` - **`velocity`** `number | null`, format: `float` - **`views`** `integer | null` - **`viewStats`** `array | null` - **`length` (required)** `integer` **Example:** ```json { "obj": { "length": 0, "data": [ { "id": 1, "tiktok_video": 1, "rank": null, "added_at": null, "velocity": null, "pre_rank": null, "peak_rank": null, "peak_date": null, "time_on_chart": 1, "views": null, "likes": null, "comments": null, "rankStats": [ { "rank": null, "posts": null, "views": null, "timestp": null } ], "viewStats": [ { "views": null, "timestp": null } ], "cm_track": null, "name": null, "isrc": null, "image_url": null, "cm_artist": 1, "artist_names": [ null ], "code2s": [ null ], "artist_images": [ null ], "artist_covers": [ null ], "album_ids": [ null ], "album_names": [ null ], "album_upc": [ null ], "album_label": [ null ], "release_dates": [ null ], "artists": [ { "id": null, "name": null, "code2": null, "image_url": null, "career_stage": null } ], "album": [ {} ], "duration_ms": null, "explicit": null, "preview_url": null, "track_genre": "", "spotify_popularity": null } ] } } ``` ### Get TikTok Top-User Chart - **Method:** `GET` - **Path:** `/api/charts/tiktok/users` - **Tags:** Charts 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. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj` (required)** `object` - **`data` (required)** `array` **Items:** - **`added_at`** `string | null`, format: `date-time` - **`cm_artist`** `integer | null` - **`daily_followers`** `integer | null` - **`daily_likes`** `integer | null` - **`followers`** `integer | null` - **`image_url`** `string | null` - **`likes`** `integer | null` - **`name`** `string | null` - **`peak_date`** `string | null`, format: `date-time` - **`peak_rank`** `integer | null` - **`pre_rank`** `integer | null` - **`rank`** `integer | null` - **`rankStats`** `array | null` - **`tiktok_user`** `object` - **`time_on_chart`** `object` - **`velocity`** `number | null`, format: `float` - **`views`** `integer | null` - **`weekly_followers`** `integer | null` - **`weekly_likes`** `integer | null` - **`length` (required)** `integer` **Example:** ```json { "obj": { "length": 0, "data": [ { "tiktok_user": 1, "cm_artist": null, "name": null, "image_url": null, "rank": null, "added_at": null, "velocity": null, "pre_rank": null, "peak_rank": null, "peak_date": null, "time_on_chart": 1, "followers": null, "likes": null, "views": null, "weekly_followers": null, "daily_followers": null, "weekly_likes": null, "daily_likes": null, "rankStats": [ { "rank": null, "posts": null, "views": null, "timestp": null } ] } ] } } ``` ### Get TikTok Tracks Chart by Type (V2 via CCC) - **Method:** `GET` - **Path:** `/api/charts/tiktok/tracks/{chart_type}` - **Tags:** Charts 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 }`). #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj` (required)** `array` **Items:** - **`album`** `object | null` - **`id`** `integer | null` - **`label`** `string | null` - **`name`** `string | null` - **`releaseDate`** `string | null`, format: `date-time` - **`artists`** `array | null` - **`chartedDate`** `string | null`, format: `date-time` - **`cityId`** `integer | null` - **`consecutivePeriods`** `integer | null` - **`countriesChartingCount`** `integer | null` - **`country`** `string | null` - **`duration`** `string | null` - **`entity`** `object | null` - **`genre`** `string | null` - **`entityId`** `integer | null` - **`externalId`** `string | null` - **`externalUrl`** `string | null` - **`genre`** `string | null` - **`imageUrl`** `string | null` - **`isChartGenre`** `boolean | null` - **`isrc`** `string | null` - **`name`** `string | null` - **`optionalFields`** `object | null` - **`peakDate`** `string | null`, format: `date-time` - **`peakRank`** `integer | null` - **`periodsOnChart`** `integer | null` - **`previewUrl`** `string | null` - **`rank`** `integer | null` - **`rankDiff`** `integer | null` - **`rankTrend`** `object` - **`targetExtras`** `object | null` - **`airplayStreams`** `integer | null` - **`amazonEdPlaylistCount`** `integer | null` - **`amazonPlaylistCount`** `integer | null` - **`anghamiLikes`** `integer | null` - **`anghamiPlays`** `integer | null` - **`deezerEdPlaylistCount`** `integer | null` - **`deezerEdPlaylistTotalReach`** `integer | null` - **`deezerPlaylistCount`** `integer | null` - **`deezerPlaylistTotalReach`** `integer | null` - **`itunesEdPlaylistCount`** `integer | null` - **`itunesPlaylistCount`** `integer | null` - **`pandoraLifetimeStationsAdded`** `integer | null` - **`pandoraLifetimeStreams`** `integer | null` - **`shazamCount`** `integer | null` - **`spotifyEdPlaylistCount`** `integer | null` - **`spotifyEdPlaylistTotalReach`** `integer | null` - **`spotifyPlaylistCount`** `integer | null` - **`spotifyPlaylistTotalReach`** `integer | null` - **`spotifyPlays`** `integer | null` - **`spotifyPopularity`** `integer | null` - **`tiktokTopVideosComments`** `integer | null` - **`tiktokTopVideosLikes`** `integer | null` - **`tiktokTopVideosViews`** `integer | null` - **`youtubeComments`** `integer | null` - **`youtubeLikes`** `integer | null` - **`youtubeViews`** `integer | null` - **`targetId`** `string | null` - **`velocity7Day`** `number | null`, format: `float` **Example:** ```json { "obj": [ { "entityId": null, "targetId": null, "duration": null, "country": null, "cityId": null, "genre": null, "rank": null, "rankDiff": null, "rankTrend": 1, "peakDate": null, "peakRank": null, "velocity7Day": null, "periodsOnChart": null, "consecutivePeriods": null, "chartedDate": null, "name": null, "imageUrl": null, "countriesChartingCount": null, "previewUrl": null, "artists": [ { "careerStage": null, "code2": null, "id": null, "name": null, "imageUrl": null } ], "album": { "id": null, "name": null, "label": null, "releaseDate": null }, "isrc": null, "entity": { "genre": null }, "externalId": null, "externalUrl": null, "optionalFields": {}, "targetExtras": { "airplayStreams": null, "amazonEdPlaylistCount": null, "amazonPlaylistCount": null, "anghamiLikes": null, "anghamiPlays": null, "deezerEdPlaylistCount": null, "deezerEdPlaylistTotalReach": null, "deezerPlaylistCount": null, "deezerPlaylistTotalReach": null, "itunesEdPlaylistCount": null, "itunesPlaylistCount": null, "pandoraLifetimeStationsAdded": null, "pandoraLifetimeStreams": null, "shazamCount": null, "spotifyEdPlaylistCount": null, "spotifyEdPlaylistTotalReach": null, "spotifyPlaylistCount": null, "spotifyPlaylistTotalReach": null, "spotifyPlays": null, "spotifyPopularity": null, "tiktokTopVideosComments": null, "tiktokTopVideosLikes": null, "tiktokTopVideosViews": null, "youtubeComments": null, "youtubeLikes": null, "youtubeViews": null }, "isChartGenre": null } ] } ``` ### Get YouTube Shorts Chart - **Method:** `GET` - **Path:** `/api/charts/youtube/shorts/{chartType}` - **Tags:** Charts 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`. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj` (required)** `array` **Items:** - **`album`** `object | null` - **`id`** `integer | null` - **`label`** `string | null` - **`name`** `string | null` - **`releaseDate`** `string | null`, format: `date-time` - **`artists`** `array | null` - **`chartedDate`** `string | null`, format: `date-time` - **`cityId`** `integer | null` - **`consecutivePeriods`** `integer | null` - **`countriesChartingCount`** `integer | null` - **`country`** `string | null` - **`duration`** `string | null` - **`entity`** `object | null` - **`genre`** `string | null` - **`entityId`** `integer | null` - **`externalId`** `string | null` - **`externalUrl`** `string | null` - **`genre`** `string | null` - **`imageUrl`** `string | null` - **`isChartGenre`** `boolean | null` - **`isrc`** `string | null` - **`name`** `string | null` - **`optionalFields`** `object | null` - **`peakDate`** `string | null`, format: `date-time` - **`peakRank`** `integer | null` - **`periodsOnChart`** `integer | null` - **`previewUrl`** `string | null` - **`rank`** `integer | null` - **`rankDiff`** `integer | null` - **`rankTrend`** `object` - **`targetExtras`** `object | null` - **`airplayStreams`** `integer | null` - **`amazonEdPlaylistCount`** `integer | null` - **`amazonPlaylistCount`** `integer | null` - **`anghamiLikes`** `integer | null` - **`anghamiPlays`** `integer | null` - **`deezerEdPlaylistCount`** `integer | null` - **`deezerEdPlaylistTotalReach`** `integer | null` - **`deezerPlaylistCount`** `integer | null` - **`deezerPlaylistTotalReach`** `integer | null` - **`itunesEdPlaylistCount`** `integer | null` - **`itunesPlaylistCount`** `integer | null` - **`pandoraLifetimeStationsAdded`** `integer | null` - **`pandoraLifetimeStreams`** `integer | null` - **`shazamCount`** `integer | null` - **`spotifyEdPlaylistCount`** `integer | null` - **`spotifyEdPlaylistTotalReach`** `integer | null` - **`spotifyPlaylistCount`** `integer | null` - **`spotifyPlaylistTotalReach`** `integer | null` - **`spotifyPlays`** `integer | null` - **`spotifyPopularity`** `integer | null` - **`tiktokTopVideosComments`** `integer | null` - **`tiktokTopVideosLikes`** `integer | null` - **`tiktokTopVideosViews`** `integer | null` - **`youtubeComments`** `integer | null` - **`youtubeLikes`** `integer | null` - **`youtubeViews`** `integer | null` - **`targetId`** `string | null` - **`velocity7Day`** `number | null`, format: `float` **Example:** ```json { "obj": [ { "entityId": null, "targetId": null, "duration": null, "country": null, "cityId": null, "genre": null, "rank": null, "rankDiff": null, "rankTrend": 1, "peakDate": null, "peakRank": null, "velocity7Day": null, "periodsOnChart": null, "consecutivePeriods": null, "chartedDate": null, "name": null, "imageUrl": null, "countriesChartingCount": null, "previewUrl": null, "artists": [ { "careerStage": null, "code2": null, "id": null, "name": null, "imageUrl": null } ], "album": { "id": null, "name": null, "label": null, "releaseDate": null }, "isrc": null, "entity": { "genre": null }, "externalId": null, "externalUrl": null, "optionalFields": {}, "targetExtras": { "airplayStreams": null, "amazonEdPlaylistCount": null, "amazonPlaylistCount": null, "anghamiLikes": null, "anghamiPlays": null, "deezerEdPlaylistCount": null, "deezerEdPlaylistTotalReach": null, "deezerPlaylistCount": null, "deezerPlaylistTotalReach": null, "itunesEdPlaylistCount": null, "itunesPlaylistCount": null, "pandoraLifetimeStationsAdded": null, "pandoraLifetimeStreams": null, "shazamCount": null, "spotifyEdPlaylistCount": null, "spotifyEdPlaylistTotalReach": null, "spotifyPlaylistCount": null, "spotifyPlaylistTotalReach": null, "spotifyPlays": null, "spotifyPopularity": null, "tiktokTopVideosComments": null, "tiktokTopVideosLikes": null, "tiktokTopVideosViews": null, "youtubeComments": null, "youtubeLikes": null, "youtubeViews": null }, "isChartGenre": null } ] } ``` ### Get YouTube Top-Track Chart (weekly) - **Method:** `GET` - **Path:** `/api/charts/youtube/tracks` - **Tags:** Charts 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. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj` (required)** `object` - **`data` (required)** `array` **Items:** - **`added_at`** `string | null`, format: `date-time` - **`album`** `object` - **`album_ids`** `array | null` - **`album_label`** `array | null` - **`album_names`** `array | null` - **`album_upc`** `array | null` - **`artist_covers`** `array | null` - **`artist_images`** `array | null` - **`artist_name`** `string | null` - **`artist_names`** `array | null` - **`artists`** `array | null` - **`cm_artist`** `object` - **`cm_track`** `integer | null` - **`code2s`** `array | null` - **`duration_ms`** `integer | null` - **`explicit`** `boolean | null` - **`id`** `string | null` - **`image_url`** `string | null` - **`isrc`** `string | null` - **`license`** `string | null` - **`name`** `string | null` - **`peak_date`** `string | null`, format: `date-time` - **`peak_rank`** `integer | null` - **`position`** `integer | null` - **`pre_rank`** `integer | null` - **`preview_url`** `string | null` - **`rank`** `integer | null` - **`rankStats`** `array | null` - **`raw_data`** `object` - **`release_dates`** `array | null` - **`spotify_popularity`** `integer | null` - **`time_on_chart`** `object` - **`track_genre`** `object` - **`type`** `integer | null` - **`upload_date`** `string | null`, format: `date-time` - **`velocity`** `number | null`, format: `float` - **`view_count`** `integer | null` - **`viewStats`** `array | null` - **`youtube_artist`** `string | null` - **`youtube_artist_cm_artist`** `integer | null` - **`youtube_artist_ids`** `array | null` - **`youtube_artist_name`** `string | null` - **`youtube_artist_names`** `array | null` - **`youtube_track_id`** `string | null` - **`youtube_track_ids`** `array | null` - **`length` (required)** `integer` **Example:** ```json { "obj": { "length": 0, "data": [ { "id": null, "youtube_track_id": null, "youtube_artist": null, "youtube_artist_name": null, "youtube_artist_cm_artist": null, "artist_name": null, "youtube_artist_ids": [ null ], "youtube_track_ids": [ null ], "youtube_artist_names": [ null ], "position": null, "rank": null, "view_count": null, "added_at": null, "upload_date": null, "license": null, "velocity": null, "pre_rank": null, "peak_rank": null, "peak_date": null, "time_on_chart": 1, "type": null, "raw_data": null, "rankStats": [ { "rank": null, "timestp": null } ], "viewStats": [ { "views": null, "timestp": null } ], "cm_track": null, "name": null, "isrc": null, "image_url": null, "cm_artist": 1, "artist_names": [ null ], "code2s": [ null ], "artist_images": [ null ], "artist_covers": [ null ], "album_ids": [ null ], "album_names": [ null ], "album_upc": [ null ], "album_label": [ null ], "release_dates": [ null ], "artists": [ { "id": null, "name": null, "code2": null, "image_url": null, "career_stage": null } ], "album": [ {} ], "duration_ms": null, "explicit": null, "preview_url": null, "track_genre": "", "spotify_popularity": null } ] } } ``` ### Get YouTube Top-Video Chart (weekly) - **Method:** `GET` - **Path:** `/api/charts/youtube/videos` - **Tags:** Charts 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. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj` (required)** `object` - **`data` (required)** `array` **Items:** - **`added_at`** `string | null`, format: `date-time` - **`album`** `object` - **`album_ids`** `array | null` - **`album_label`** `array | null` - **`album_names`** `array | null` - **`album_upc`** `array | null` - **`artist_covers`** `array | null` - **`artist_images`** `array | null` - **`artist_names`** `array | null` - **`artists`** `array | null` - **`cm_artist`** `object` - **`cm_track`** `integer | null` - **`code2s`** `array | null` - **`duration_ms`** `integer | null` - **`explicit`** `boolean | null` - **`id`** `object` - **`image_url`** `string | null` - **`isrc`** `string | null` - **`license`** `string | null` - **`name`** `string | null` - **`peak_date`** `string | null`, format: `date-time` - **`peak_rank`** `integer | null` - **`position`** `integer | null` - **`pre_rank`** `integer | null` - **`preview_url`** `string | null` - **`rank`** `integer | null` - **`rankStats`** `array | null` - **`release_dates`** `array | null` - **`spotify_popularity`** `integer | null` - **`time_on_chart`** `object` - **`track_genre`** `object` - **`upload_date`** `string | null`, format: `date-time` - **`velocity`** `number | null`, format: `float` - **`view_count`** `integer | null` - **`viewStats`** `array | null` - **`youtube`** `object` - **`length` (required)** `integer` **Example:** ```json { "obj": { "length": 0, "data": [ { "id": 1, "youtube": "", "position": null, "rank": null, "view_count": null, "added_at": null, "upload_date": null, "license": null, "velocity": null, "pre_rank": null, "peak_rank": null, "peak_date": null, "time_on_chart": 1, "rankStats": [ { "rank": null, "timestp": null } ], "viewStats": [ { "views": null, "timestp": null } ], "cm_track": null, "name": null, "isrc": null, "image_url": null, "cm_artist": 1, "artist_names": [ null ], "code2s": [ null ], "artist_images": [ null ], "artist_covers": [ null ], "album_ids": [ null ], "album_names": [ null ], "album_upc": [ null ], "album_label": [ null ], "release_dates": [ null ], "artists": [ { "id": null, "name": null, "code2": null, "image_url": null, "career_stage": null } ], "album": [ {} ], "duration_ms": null, "explicit": null, "preview_url": null, "track_genre": "", "spotify_popularity": null } ] } } ``` ### Get YouTube Trend Chart (weekly) - **Method:** `GET` - **Path:** `/api/charts/youtube/trends` - **Tags:** Charts 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. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj` (required)** `object` - **`data` (required)** `array` **Items:** - **`added_at`** `string | null`, format: `date-time` - **`album`** `object` - **`album_ids`** `array | null` - **`album_label`** `array | null` - **`album_names`** `array | null` - **`album_upc`** `array | null` - **`artist_covers`** `array | null` - **`artist_images`** `array | null` - **`artist_name`** `string | null` - **`artist_names`** `array | null` - **`artists`** `array | null` - **`batch_ids`** `object` - **`cm_artist`** `object` - **`cm_track`** `integer | null` - **`code2s`** `array | null` - **`composer_name`** `string | null` - **`doc_id`** `string | null` - **`duration_ms`** `integer | null` - **`explicit`** `boolean | null` - **`genre`** `string | null` - **`genre_smart_ordered`** `array | null` - **`id`** `object` - **`image_url`** `string | null` - **`isrc`** `string | null` - **`latest`** `object | null` - **`license`** `string | null` - **`name`** `string | null` - **`peak_date`** `string | null`, format: `date-time` - **`peak_rank`** `integer | null` - **`position`** `integer | null` - **`pre_rank`** `integer | null` - **`preview_url`** `string | null` - **`rankStats`** `array | null` - **`raw_data`** `object` - **`release_dates`** `array | null` - **`score`** `number | null`, format: `float` - **`spotify_popularity`** `integer | null` - **`tags`** `object` - **`time_on_chart`** `object` - **`track_genre`** `object` - **`upload_date`** `string | null`, format: `date-time` - **`velocity`** `number | null`, format: `float` - **`youtube`** `object` - **`youtube_artist`** `string | null` - **`youtube_artist_ids`** `array | null` - **`youtube_artist_names`** `array | null` - **`youtube_track_ids`** `array | null` - **`youtube_video_id`** `string | null` - **`length` (required)** `integer` **Example:** ```json { "obj": { "length": 0, "data": [ { "id": 1, "youtube": "", "youtube_video_id": null, "name": null, "artist_name": null, "youtube_artist": null, "youtube_artist_names": [ null ], "cm_artist": 1, "artist_names": [ null ], "artists": [ { "id": null, "name": null, "code2": null } ], "isrc": null, "cm_track": null, "duration_ms": null, "explicit": null, "composer_name": null, "upload_date": null, "added_at": null, "peak_date": null, "image_url": null, "preview_url": null, "position": null, "velocity": null, "pre_rank": null, "peak_rank": null, "time_on_chart": 1, "raw_data": null, "album_names": [ null ], "album": null, "album_ids": [ null ], "album_upc": [ null ], "album_label": [ null ], "genre": null, "genre_smart_ordered": [ {} ], "tags": "", "track_genre": "", "spotify_popularity": null, "latest": {}, "score": null, "license": null, "code2s": [ null ], "artist_images": [ null ], "artist_covers": [ null ], "youtube_artist_ids": [ null ], "youtube_track_ids": [ null ], "release_dates": [ "" ], "doc_id": null, "batch_ids": null, "rankStats": [ { "rank": null, "views": null, "timestp": null } ] } ] } } ``` ### Get YouTube Top-Artist Chart (weekly) - **Method:** `GET` - **Path:** `/api/charts/youtube/artists` - **Tags:** Charts 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. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj` (required)** `object` - **`data` (required)** `array` **Items:** - **`added_at`** `string | null`, format: `date-time` - **`cm_artist`** `integer | null` - **`image_url`** `string | null` - **`name`** `string | null` - **`peak_date`** `string | null`, format: `date-time` - **`peak_rank`** `integer | null` - **`position`** `integer | null` - **`pre_rank`** `integer | null` - **`rank`** `integer | null` - **`rankStats`** `array | null` - **`subscriber_count`** `integer | null` - **`time_on_chart`** `object` - **`velocity`** `number | null`, format: `float` - **`view_count`** `integer | null` - **`viewStats`** `array | null` - **`youtube_artist`** `string | null` - **`length` (required)** `integer` **Example:** ```json { "obj": { "length": 0, "data": [ { "cm_artist": null, "youtube_artist": null, "name": null, "image_url": null, "rank": null, "position": null, "view_count": null, "subscriber_count": null, "added_at": null, "velocity": null, "pre_rank": null, "peak_rank": null, "peak_date": null, "time_on_chart": 1, "rankStats": [ { "rank": null, "timestp": null } ], "viewStats": [ { "views": null, "timestp": null } ] } ] } } ``` ### Airplay Track Charts - **Method:** `GET` - **Path:** `/api/charts/airplay/tracks` - **Tags:** Charts 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`. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj`** `object` - **`data`** `array | null` - **`length`** `integer | null` **Example:** ```json { "obj": { "length": null, "data": [ { "id": 0, "name": null, "isrc": null, "image_url": null, "description": null, "tags": null, "cm_track": null, "cm_artist": [ null ], "artist_names": [ null ], "code2s": [ null ], "artist_images": [ null ], "artist_covers": [ null ], "spotify_track_ids": [ null ], "spotify_album_ids": [ null ], "spotify_duration_ms": null, "itunes_track_ids": [ null ], "itunes_album_ids": [ null ], "itunes_artist_ids": [ 1 ], "itunes_artist_names": [ null ], "storefronts": [ null ], "deezer_track_ids": [ null ], "deezer_album_ids": [ 1 ], "deezer_duration": null, "amazon_track_ids": [ null ], "amazon_album_ids": [ null ], "album_ids": [ 0 ], "album_names": [ null ], "album_upc": [ null ], "album_label": [ null ], "release_dates": [ "" ], "created_at": "", "modified_at": "", "rank": null, "pre_rank": null, "peak_rank": null, "peak_date": "", "added_at": "", "velocity": null, "time_on_chart": "", "code2": null, "city_id": null, "plays": 1, "count": 1, "weekly_count": 1, "rankStats": [ { "rank": null, "plays": 1, "timestp": "" } ] } ] } } ``` ### Airplay Artist Charts - **Method:** `GET` - **Path:** `/api/charts/airplay/artists` - **Tags:** Charts 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`. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj`** `object` - **`data`** `array | null` - **`length`** `integer | null` **Example:** ```json { "obj": { "length": null, "data": [ { "rank": null, "pre_rank": null, "peak_rank": null, "peak_date": "", "added_at": "", "velocity": null, "time_on_chart": "", "code2": null, "city_id": null, "plays": 1, "cm_artist": null, "id": 0, "name": null, "image_url": null, "isni": null, "hometown_city": null, "current_city": null, "sp_followers": null, "sp_popularity": null, "sp_monthly_listeners": null, "deezer_fans": null, "tags": [], "spotify_artist_ids": [ 1 ], "itunes_artist_ids": [ 1 ], "deezer_artist_ids": [ 1 ], "amazon_artist_ids": [ 1 ], "cm_artist_rank": null, "rankStats": [ { "rank": null, "plays": 1, "timestp": "" } ] } ] } } ``` ### Twitch User Charts - **Method:** `GET` - **Path:** `/api/charts/twitch/users` - **Tags:** Charts 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`. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj`** `object` - **`data`** `array | null` - **`length`** `integer | null` **Example:** ```json { "obj": { "length": null, "data": [ { "rank": null, "pre_rank": null, "peak_rank": null, "peak_date": "", "added_at": "", "velocity": null, "time_on_chart": "", "twitch_user": 0, "followers": 1, "weekly_followers": 1, "monthly_followers": 1, "count": 1, "weekly_count": 1, "monthly_count": 1, "name": null, "image_url": null, "link": null, "cm_artist": null, "rankStats": [ { "rank": null, "followers": 1, "timestp": "" } ] } ] } } ``` ### Melon Track Chart - **Method:** `GET` - **Path:** `/api/charts/melon/track/{chartType}` - **Tags:** Charts 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. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj`** `array | null` **Example:** ```json { "obj": [ { "entityId": null, "targetId": "", "duration": null, "country": null, "cityId": null, "genre": null, "rank": null, "rankDiff": null, "rankTrend": [ { "timestp": null, "rank": "" } ], "peakDate": null, "peakRank": null, "velocity7Day": null, "periodsOnChart": null, "consecutivePeriods": null, "chartedDate": null, "name": null, "imageUrl": null, "createdAt": null, "artists": [ { "id": null, "name": null, "code2": null, "careerStage": null, "imageUrl": null } ], "album": { "id": null, "name": null, "label": null, "releaseDate": null }, "optionalRows": { "overallRank": null, "videos": null, "totalVideos": null, "metricValue": null, "metricDiff": null, "avgPosition": null, "score": null, "totalFollowers": null, "velocity": null, "isComeback": null, "plays": null, "playsWeekly": null, "counts": null, "index": null, "comments": null, "artistName": null, "label": null, "physicalRecordIndex": null, "albumName": null, "name": null, "imageUrl": null, "id": "", "platformId": "" }, "optionalFields": { "overallRank": null, "videos": null, "totalVideos": null, "metricValue": null, "metricDiff": null, "avgPosition": null, "score": null, "totalFollowers": null, "velocity": null, "isComeback": null, "plays": null, "playsWeekly": null, "counts": null, "index": null, "comments": null, "artistName": null, "label": null, "physicalRecordIndex": null, "albumName": null, "name": null, "imageUrl": null, "id": "", "platformId": "" }, "targetExtras": { "airplayStreams": null, "amazonEdPlaylistCount": null, "amazonPlaylistCount": null, "anghamiLikes": null, "anghamiPlays": null, "deezerEdPlaylistCount": null, "deezerEdPlaylistTotalReach": null, "deezerPlaylistCount": null, "deezerPlaylistTotalReach": null, "itunesEdPlaylistCount": null, "itunesPlaylistCount": null, "lineMusicLikes": null, "lineMusicListenCount": null, "melonComments": null, "melonLikes": null, "pandoraLifetimeStationsAdded": null, "pandoraLifetimeStreams": null, "shazamCount": null, "siriusxmStreams": null, "soundcloudPlays": null, "spotifyEdPlaylistCount": null, "spotifyEdPlaylistTotalReach": null, "spotifyPlaylistCount": null, "spotifyPlaylistTotalReach": null, "spotifyPlays": null, "spotifyPopularity": null, "tiktokTopVideosComments": null, "tiktokTopVideosLikes": null, "tiktokTopVideosViews": null, "youtubeComments": null, "youtubeEdPlaylistCount": null, "youtubeEdPlaylistTotalReach": null, "youtubeLikes": null, "youtubePlaylistCount": null, "youtubePlaylistTotalReach": null, "youtubeViews": null }, "isChartGenre": null, "externalId": "", "externalUrl": null, "isrc": null, "entityGenre": null, "id": "", "platform_id": "" } ] } ``` ### Hanteo Chart - **Method:** `GET` - **Path:** `/api/charts/hanteo/{entityType}/{chartType}` - **Tags:** Charts 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`. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj`** `array | null` **Example:** ```json { "obj": [ { "entityId": null, "targetId": "", "duration": null, "country": null, "cityId": null, "genre": null, "rank": null, "rankDiff": null, "rankTrend": [ { "timestp": null, "rank": "" } ], "peakDate": null, "peakRank": null, "velocity7Day": null, "periodsOnChart": null, "consecutivePeriods": null, "chartedDate": null, "name": null, "imageUrl": null, "createdAt": null, "artists": [ { "id": null, "name": null, "code2": null, "careerStage": null, "imageUrl": null } ], "album": { "id": null, "name": null, "label": null, "releaseDate": null }, "optionalRows": { "overallRank": null, "videos": null, "totalVideos": null, "metricValue": null, "metricDiff": null, "avgPosition": null, "score": null, "totalFollowers": null, "velocity": null, "isComeback": null, "plays": null, "playsWeekly": null, "counts": null, "index": null, "comments": null, "artistName": null, "label": null, "physicalRecordIndex": null, "albumName": null, "name": null, "imageUrl": null, "id": "", "platformId": "" }, "optionalFields": { "overallRank": null, "videos": null, "totalVideos": null, "metricValue": null, "metricDiff": null, "avgPosition": null, "score": null, "totalFollowers": null, "velocity": null, "isComeback": null, "plays": null, "playsWeekly": null, "counts": null, "index": null, "comments": null, "artistName": null, "label": null, "physicalRecordIndex": null, "albumName": null, "name": null, "imageUrl": null, "id": "", "platformId": "" }, "targetExtras": { "airplayStreams": null, "amazonEdPlaylistCount": null, "amazonPlaylistCount": null, "anghamiLikes": null, "anghamiPlays": null, "deezerEdPlaylistCount": null, "deezerEdPlaylistTotalReach": null, "deezerPlaylistCount": null, "deezerPlaylistTotalReach": null, "itunesEdPlaylistCount": null, "itunesPlaylistCount": null, "lineMusicLikes": null, "lineMusicListenCount": null, "melonComments": null, "melonLikes": null, "pandoraLifetimeStationsAdded": null, "pandoraLifetimeStreams": null, "shazamCount": null, "siriusxmStreams": null, "soundcloudPlays": null, "spotifyEdPlaylistCount": null, "spotifyEdPlaylistTotalReach": null, "spotifyPlaylistCount": null, "spotifyPlaylistTotalReach": null, "spotifyPlays": null, "spotifyPopularity": null, "tiktokTopVideosComments": null, "tiktokTopVideosLikes": null, "tiktokTopVideosViews": null, "youtubeComments": null, "youtubeEdPlaylistCount": null, "youtubeEdPlaylistTotalReach": null, "youtubeLikes": null, "youtubePlaylistCount": null, "youtubePlaylistTotalReach": null, "youtubeViews": null }, "isChartGenre": null, "externalId": "", "externalUrl": null, "isrc": null, "entityGenre": null, "id": "", "platform_id": "" } ] } ``` ### Circle Chart - **Method:** `GET` - **Path:** `/api/charts/circle/{entityType}/{chartType}` - **Tags:** Charts 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`. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj`** `array | null` **Example:** ```json { "obj": [ { "entityId": null, "targetId": "", "duration": null, "country": null, "cityId": null, "genre": null, "rank": null, "rankDiff": null, "rankTrend": [ { "timestp": null, "rank": "" } ], "peakDate": null, "peakRank": null, "velocity7Day": null, "periodsOnChart": null, "consecutivePeriods": null, "chartedDate": null, "name": null, "imageUrl": null, "createdAt": null, "artists": [ { "id": null, "name": null, "code2": null, "careerStage": null, "imageUrl": null } ], "album": { "id": null, "name": null, "label": null, "releaseDate": null }, "optionalRows": { "overallRank": null, "videos": null, "totalVideos": null, "metricValue": null, "metricDiff": null, "avgPosition": null, "score": null, "totalFollowers": null, "velocity": null, "isComeback": null, "plays": null, "playsWeekly": null, "counts": null, "index": null, "comments": null, "artistName": null, "label": null, "physicalRecordIndex": null, "albumName": null, "name": null, "imageUrl": null, "id": "", "platformId": "" }, "optionalFields": { "overallRank": null, "videos": null, "totalVideos": null, "metricValue": null, "metricDiff": null, "avgPosition": null, "score": null, "totalFollowers": null, "velocity": null, "isComeback": null, "plays": null, "playsWeekly": null, "counts": null, "index": null, "comments": null, "artistName": null, "label": null, "physicalRecordIndex": null, "albumName": null, "name": null, "imageUrl": null, "id": "", "platformId": "" }, "targetExtras": { "airplayStreams": null, "amazonEdPlaylistCount": null, "amazonPlaylistCount": null, "anghamiLikes": null, "anghamiPlays": null, "deezerEdPlaylistCount": null, "deezerEdPlaylistTotalReach": null, "deezerPlaylistCount": null, "deezerPlaylistTotalReach": null, "itunesEdPlaylistCount": null, "itunesPlaylistCount": null, "lineMusicLikes": null, "lineMusicListenCount": null, "melonComments": null, "melonLikes": null, "pandoraLifetimeStationsAdded": null, "pandoraLifetimeStreams": null, "shazamCount": null, "siriusxmStreams": null, "soundcloudPlays": null, "spotifyEdPlaylistCount": null, "spotifyEdPlaylistTotalReach": null, "spotifyPlaylistCount": null, "spotifyPlaylistTotalReach": null, "spotifyPlays": null, "spotifyPopularity": null, "tiktokTopVideosComments": null, "tiktokTopVideosLikes": null, "tiktokTopVideosViews": null, "youtubeComments": null, "youtubeEdPlaylistCount": null, "youtubeEdPlaylistTotalReach": null, "youtubeLikes": null, "youtubePlaylistCount": null, "youtubePlaylistTotalReach": null, "youtubeViews": null }, "isChartGenre": null, "externalId": "", "externalUrl": null, "isrc": null, "entityGenre": null, "id": "", "platform_id": "" } ] } ``` ### Line Music Chart - **Method:** `GET` - **Path:** `/api/charts/line_music/{entityType}/{chartType}` - **Tags:** Charts Return Line Music chart entries for the given `entityType` (`track` or `album`). Shape matches the generic regional CCC chart row. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj`** `array | null` **Example:** ```json { "obj": [ { "entityId": null, "targetId": "", "duration": null, "country": null, "cityId": null, "genre": null, "rank": null, "rankDiff": null, "rankTrend": [ { "timestp": null, "rank": "" } ], "peakDate": null, "peakRank": null, "velocity7Day": null, "periodsOnChart": null, "consecutivePeriods": null, "chartedDate": null, "name": null, "imageUrl": null, "createdAt": null, "artists": [ { "id": null, "name": null, "code2": null, "careerStage": null, "imageUrl": null } ], "album": { "id": null, "name": null, "label": null, "releaseDate": null }, "optionalRows": { "overallRank": null, "videos": null, "totalVideos": null, "metricValue": null, "metricDiff": null, "avgPosition": null, "score": null, "totalFollowers": null, "velocity": null, "isComeback": null, "plays": null, "playsWeekly": null, "counts": null, "index": null, "comments": null, "artistName": null, "label": null, "physicalRecordIndex": null, "albumName": null, "name": null, "imageUrl": null, "id": "", "platformId": "" }, "optionalFields": { "overallRank": null, "videos": null, "totalVideos": null, "metricValue": null, "metricDiff": null, "avgPosition": null, "score": null, "totalFollowers": null, "velocity": null, "isComeback": null, "plays": null, "playsWeekly": null, "counts": null, "index": null, "comments": null, "artistName": null, "label": null, "physicalRecordIndex": null, "albumName": null, "name": null, "imageUrl": null, "id": "", "platformId": "" }, "targetExtras": { "airplayStreams": null, "amazonEdPlaylistCount": null, "amazonPlaylistCount": null, "anghamiLikes": null, "anghamiPlays": null, "deezerEdPlaylistCount": null, "deezerEdPlaylistTotalReach": null, "deezerPlaylistCount": null, "deezerPlaylistTotalReach": null, "itunesEdPlaylistCount": null, "itunesPlaylistCount": null, "lineMusicLikes": null, "lineMusicListenCount": null, "melonComments": null, "melonLikes": null, "pandoraLifetimeStationsAdded": null, "pandoraLifetimeStreams": null, "shazamCount": null, "siriusxmStreams": null, "soundcloudPlays": null, "spotifyEdPlaylistCount": null, "spotifyEdPlaylistTotalReach": null, "spotifyPlaylistCount": null, "spotifyPlaylistTotalReach": null, "spotifyPlays": null, "spotifyPopularity": null, "tiktokTopVideosComments": null, "tiktokTopVideosLikes": null, "tiktokTopVideosViews": null, "youtubeComments": null, "youtubeEdPlaylistCount": null, "youtubeEdPlaylistTotalReach": null, "youtubeLikes": null, "youtubePlaylistCount": null, "youtubePlaylistTotalReach": null, "youtubeViews": null }, "isChartGenre": null, "externalId": "", "externalUrl": null, "isrc": null, "entityGenre": null, "id": "", "platform_id": "" } ] } ``` ### Pandora Track Chart - **Method:** `GET` - **Path:** `/api/charts/pandora/track/{chartType}` - **Tags:** Charts Return Pandora track chart entries. Served by the CCC (`cm_chart_cache_v2`) pipeline. No `duration` / `genre` filters are forwarded — router only accepts `date`, `limit`, `offset`, `latest`. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj`** `array | null` **Example:** ```json { "obj": [ { "entityId": null, "targetId": "", "duration": null, "country": null, "cityId": null, "genre": null, "rank": null, "rankDiff": null, "rankTrend": [ { "timestp": null, "rank": "" } ], "peakDate": null, "peakRank": null, "velocity7Day": null, "periodsOnChart": null, "consecutivePeriods": null, "chartedDate": null, "name": null, "imageUrl": null, "createdAt": null, "artists": [ { "id": null, "name": null, "code2": null, "careerStage": null, "imageUrl": null } ], "album": { "id": null, "name": null, "label": null, "releaseDate": null }, "optionalRows": { "overallRank": null, "videos": null, "totalVideos": null, "metricValue": null, "metricDiff": null, "avgPosition": null, "score": null, "totalFollowers": null, "velocity": null, "isComeback": null, "plays": null, "playsWeekly": null, "counts": null, "index": null, "comments": null, "artistName": null, "label": null, "physicalRecordIndex": null, "albumName": null, "name": null, "imageUrl": null, "id": "", "platformId": "" }, "optionalFields": { "overallRank": null, "videos": null, "totalVideos": null, "metricValue": null, "metricDiff": null, "avgPosition": null, "score": null, "totalFollowers": null, "velocity": null, "isComeback": null, "plays": null, "playsWeekly": null, "counts": null, "index": null, "comments": null, "artistName": null, "label": null, "physicalRecordIndex": null, "albumName": null, "name": null, "imageUrl": null, "id": "", "platformId": "" }, "targetExtras": { "airplayStreams": null, "amazonEdPlaylistCount": null, "amazonPlaylistCount": null, "anghamiLikes": null, "anghamiPlays": null, "deezerEdPlaylistCount": null, "deezerEdPlaylistTotalReach": null, "deezerPlaylistCount": null, "deezerPlaylistTotalReach": null, "itunesEdPlaylistCount": null, "itunesPlaylistCount": null, "lineMusicLikes": null, "lineMusicListenCount": null, "melonComments": null, "melonLikes": null, "pandoraLifetimeStationsAdded": null, "pandoraLifetimeStreams": null, "shazamCount": null, "siriusxmStreams": null, "soundcloudPlays": null, "spotifyEdPlaylistCount": null, "spotifyEdPlaylistTotalReach": null, "spotifyPlaylistCount": null, "spotifyPlaylistTotalReach": null, "spotifyPlays": null, "spotifyPopularity": null, "tiktokTopVideosComments": null, "tiktokTopVideosLikes": null, "tiktokTopVideosViews": null, "youtubeComments": null, "youtubeEdPlaylistCount": null, "youtubeEdPlaylistTotalReach": null, "youtubeLikes": null, "youtubePlaylistCount": null, "youtubePlaylistTotalReach": null, "youtubeViews": null }, "isChartGenre": null, "externalId": "", "externalUrl": null, "isrc": null, "entityGenre": null, "id": "", "platform_id": "" } ] } ``` ### Anghami Track Chart - **Method:** `GET` - **Path:** `/api/charts/anghami/track/{chartType}` - **Tags:** Charts 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. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj`** `array | null` **Example:** ```json { "obj": [ { "entityId": null, "targetId": "", "duration": null, "country": null, "cityId": null, "genre": null, "rank": null, "rankDiff": null, "rankTrend": [ { "timestp": null, "rank": "" } ], "peakDate": null, "peakRank": null, "velocity7Day": null, "periodsOnChart": null, "consecutivePeriods": null, "chartedDate": null, "name": null, "imageUrl": null, "createdAt": null, "artists": [ { "id": null, "name": null, "code2": null, "careerStage": null, "imageUrl": null } ], "album": { "id": null, "name": null, "label": null, "releaseDate": null }, "optionalRows": { "overallRank": null, "videos": null, "totalVideos": null, "metricValue": null, "metricDiff": null, "avgPosition": null, "score": null, "totalFollowers": null, "velocity": null, "isComeback": null, "plays": null, "playsWeekly": null, "counts": null, "index": null, "comments": null, "artistName": null, "label": null, "physicalRecordIndex": null, "albumName": null, "name": null, "imageUrl": null, "id": "", "platformId": "" }, "optionalFields": { "overallRank": null, "videos": null, "totalVideos": null, "metricValue": null, "metricDiff": null, "avgPosition": null, "score": null, "totalFollowers": null, "velocity": null, "isComeback": null, "plays": null, "playsWeekly": null, "counts": null, "index": null, "comments": null, "artistName": null, "label": null, "physicalRecordIndex": null, "albumName": null, "name": null, "imageUrl": null, "id": "", "platformId": "" }, "targetExtras": { "airplayStreams": null, "amazonEdPlaylistCount": null, "amazonPlaylistCount": null, "anghamiLikes": null, "anghamiPlays": null, "deezerEdPlaylistCount": null, "deezerEdPlaylistTotalReach": null, "deezerPlaylistCount": null, "deezerPlaylistTotalReach": null, "itunesEdPlaylistCount": null, "itunesPlaylistCount": null, "lineMusicLikes": null, "lineMusicListenCount": null, "melonComments": null, "melonLikes": null, "pandoraLifetimeStationsAdded": null, "pandoraLifetimeStreams": null, "shazamCount": null, "siriusxmStreams": null, "soundcloudPlays": null, "spotifyEdPlaylistCount": null, "spotifyEdPlaylistTotalReach": null, "spotifyPlaylistCount": null, "spotifyPlaylistTotalReach": null, "spotifyPlays": null, "spotifyPopularity": null, "tiktokTopVideosComments": null, "tiktokTopVideosLikes": null, "tiktokTopVideosViews": null, "youtubeComments": null, "youtubeEdPlaylistCount": null, "youtubeEdPlaylistTotalReach": null, "youtubeLikes": null, "youtubePlaylistCount": null, "youtubePlaylistTotalReach": null, "youtubeViews": null }, "isChartGenre": null, "externalId": "", "externalUrl": null, "isrc": null, "entityGenre": null, "id": "", "platform_id": "" } ] } ``` ### SoundCloud Track Chart - **Method:** `GET` - **Path:** `/api/charts/soundcloud/track/{chartType}` - **Tags:** Charts 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`. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj`** `array | null` **Example:** ```json { "obj": [ { "entityId": null, "targetId": "", "duration": null, "country": null, "cityId": null, "genre": null, "rank": null, "rankDiff": null, "rankTrend": [ { "timestp": null, "rank": "" } ], "peakDate": null, "peakRank": null, "velocity7Day": null, "periodsOnChart": null, "consecutivePeriods": null, "chartedDate": null, "name": null, "imageUrl": null, "createdAt": null, "artists": [ { "id": null, "name": null, "code2": null, "careerStage": null, "imageUrl": null } ], "album": { "id": null, "name": null, "label": null, "releaseDate": null }, "optionalRows": { "overallRank": null, "videos": null, "totalVideos": null, "metricValue": null, "metricDiff": null, "avgPosition": null, "score": null, "totalFollowers": null, "velocity": null, "isComeback": null, "plays": null, "playsWeekly": null, "counts": null, "index": null, "comments": null, "artistName": null, "label": null, "physicalRecordIndex": null, "albumName": null, "name": null, "imageUrl": null, "id": "", "platformId": "" }, "optionalFields": { "overallRank": null, "videos": null, "totalVideos": null, "metricValue": null, "metricDiff": null, "avgPosition": null, "score": null, "totalFollowers": null, "velocity": null, "isComeback": null, "plays": null, "playsWeekly": null, "counts": null, "index": null, "comments": null, "artistName": null, "label": null, "physicalRecordIndex": null, "albumName": null, "name": null, "imageUrl": null, "id": "", "platformId": "" }, "targetExtras": { "airplayStreams": null, "amazonEdPlaylistCount": null, "amazonPlaylistCount": null, "anghamiLikes": null, "anghamiPlays": null, "deezerEdPlaylistCount": null, "deezerEdPlaylistTotalReach": null, "deezerPlaylistCount": null, "deezerPlaylistTotalReach": null, "itunesEdPlaylistCount": null, "itunesPlaylistCount": null, "lineMusicLikes": null, "lineMusicListenCount": null, "melonComments": null, "melonLikes": null, "pandoraLifetimeStationsAdded": null, "pandoraLifetimeStreams": null, "shazamCount": null, "siriusxmStreams": null, "soundcloudPlays": null, "spotifyEdPlaylistCount": null, "spotifyEdPlaylistTotalReach": null, "spotifyPlaylistCount": null, "spotifyPlaylistTotalReach": null, "spotifyPlays": null, "spotifyPopularity": null, "tiktokTopVideosComments": null, "tiktokTopVideosLikes": null, "tiktokTopVideosViews": null, "youtubeComments": null, "youtubeEdPlaylistCount": null, "youtubeEdPlaylistTotalReach": null, "youtubeLikes": null, "youtubePlaylistCount": null, "youtubePlaylistTotalReach": null, "youtubeViews": null }, "isChartGenre": null, "externalId": "", "externalUrl": null, "isrc": null, "entityGenre": null, "id": "", "platform_id": "" } ] } ``` ### List Chart Countries for Platform - **Method:** `GET` - **Path:** `/api/charts/{platform}/countries` - **Tags:** Charts 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. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj`** `object | null` - **`countries`** `object` **Example:** ```json { "obj": { "countries": [ "" ] } } ``` ### List Chart Dates for Streaming Type - **Method:** `GET` - **Path:** `/api/charts/{streamingType}/dates` - **Tags:** Charts Return the dates with available chart data for the given `streamingType`. Source varies by platform: S3, Snowflake, ClickHouse, or RDS (see `ChartDatesService.getChartDatesDataSource`). Returns an array of `{ timestp }` objects wrapped by `handleDBResponse(res, "obj")`. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj`** `array | null` **Example:** ```json { "obj": [ { "timestp": null } ] } ``` ### List Chart Genres for Platform - **Method:** `GET` - **Path:** `/api/charts/genres/{platform}` - **Tags:** Charts 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. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj`** `array | null` **Example:** ```json { "obj": [ "" ] } ``` ### List Top Artists in a City - **Method:** `GET` - **Path:** `/api/city/{id}/{domain}/top-artists` - **Tags:** City Top artists in a city for a given platform (`domain` in `spotify | youtube | shazam | cm | 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`. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj` (required)** `array` **Items:** - **`id` (required)** `integer` - **`amazon_artist_ids`** `array | null` - **`band`** `boolean | null` - **`cm_artist_rank`** `integer | null` - **`cm_artist_score`** `number | null`, format: `float` - **`code2`** `string | null` - **`count`** `object` - **`current_city`** `string | null` - **`deezer_artist_ids`** `array | null` - **`deezer_fans`** `integer | null` - **`gender`** `string | null` - **`hometown_city`** `string | null` - **`image_url`** `string | null` - **`isni`** `string | null` - **`itunes_artist_ids`** `array | null` - **`latest_release`** `object | null` - **`album_name`** `string | null` - **`cm_album`** `integer | null` - **`image_url`** `string | null` - **`label`** `string | null` - **`release_date`** `string | null`, format: `date-time` - **`upc`** `string | null` - **`name`** `string | null` - **`primary_genre_smart`** `object` - **`sp_followers`** `integer | null` - **`sp_monthly_listeners`** `integer | null` - **`sp_popularity`** `integer | null` - **`spotify_artist_ids`** `array | null` - **`tags`** `array | null` - **`username`** `string | null` - **`verified`** `boolean | null` **Example:** ```json { "obj": [ { "count": 1, "username": null, "id": 0, "name": null, "image_url": null, "isni": null, "code2": null, "hometown_city": null, "current_city": null, "verified": null, "band": null, "gender": null, "sp_followers": null, "sp_popularity": null, "sp_monthly_listeners": null, "deezer_fans": null, "cm_artist_rank": null, "cm_artist_score": null, "primary_genre_smart": 1, "tags": [ "" ], "spotify_artist_ids": [ null ], "itunes_artist_ids": [ null ], "deezer_artist_ids": [ null ], "amazon_artist_ids": [ null ], "latest_release": { "cm_album": null, "album_name": null, "release_date": null, "upc": null, "label": null, "image_url": null } } ] } ``` ### List Top Tracks in a City - **Method:** `GET` - **Path:** `/api/city/{id}/{domain}/top-tracks` - **Tags:** City 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`. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj` (required)** `array` **Items:** - **`isrc` (required)** `string` - **`album_ids`** `array | null` - **`album_label`** `array | null` - **`album_names`** `array | null` - **`album_upc`** `array | null` - **`amazon_album_ids`** `array | null` - **`amazon_track_ids`** `array | null` - **`artist_covers`** `array | null` - **`artist_images`** `array | null` - **`artist_names`** `array | null` - **`artists`** `array | null` - **`cm_artist`** `array | null` - **`cm_track`** `integer | null` - **`code2s`** `array | null` - **`count`** `object` - **`created_at`** `object` - **`deezer_album_ids`** `array | null` - **`deezer_duration`** `integer | null` - **`deezer_track_ids`** `array | null` - **`description`** `string | null` - **`id`** `integer | null` - **`image_url`** `string | null` - **`itunes_album_ids`** `array | null` - **`itunes_track_ids`** `array | null` - **`modified_at`** `object` - **`name`** `string | null` - **`position_stats`** `array | null` - **`release_dates`** `array | null` - **`spotify_album_ids`** `array | null` - **`spotify_duration_ms`** `integer | null` - **`spotify_track_ids`** `array | null` - **`storefronts`** `array | null` - **`tags`** `object` **Example:** ```json { "obj": [ { "isrc": "", "count": 1, "position_stats": [ { "timestp": "", "position": null } ], "id": null, "name": null, "image_url": null, "description": null, "created_at": "", "modified_at": "", "tags": "", "cm_track": null, "cm_artist": [ 1 ], "artist_names": [ null ], "code2s": [ null ], "artist_images": [ null ], "artist_covers": [ null ], "artists": [ { "id": null, "name": null } ], "spotify_track_ids": [ null ], "spotify_album_ids": [ null ], "spotify_duration_ms": null, "itunes_track_ids": [ null ], "itunes_album_ids": [ null ], "storefronts": [ "" ], "deezer_track_ids": [ null ], "deezer_album_ids": [ null ], "deezer_duration": null, "amazon_track_ids": [ null ], "amazon_album_ids": [ null ], "album_ids": [ null ], "album_names": [ null ], "album_upc": [ null ], "album_label": [ null ], "release_dates": [ "" ] } ] } ``` ### List Artist Rankings by Country - **Method:** `GET` - **Path:** `/api/country/{code2}/artist-rankings/{area}/{type}/{subArea}` - **Tags:** Country 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. `local_rank_trend` is only populated when `type=audience`. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj` (required)** `array` **Items:** - **`id` (required)** `integer` - **`local_rank` (required)** `integer` - **`amazon_artist_ids`** `array | null` - **`band`** `boolean | null` - **`cm_artist_rank`** `integer | null` - **`cm_artist_score`** `number | null`, format: `float` - **`code2`** `string | null` - **`current_city`** `string | null` - **`deezer_artist_ids`** `array | null` - **`deezer_fans`** `integer | null` - **`gender`** `string | null` - **`hometown_city`** `string | null` - **`image_url`** `string | null` - **`isni`** `string | null` - **`itunes_artist_ids`** `array | null` - **`local_rank_trend`** `array` **Items:** - **`name`** `string | null` - **`primary_genre_smart`** `object` - **`sp_followers`** `integer | null` - **`sp_monthly_listeners`** `integer | null` - **`sp_popularity`** `integer | null` - **`spotify_artist_ids`** `array | null` - **`tags`** `array | null` - **`verified`** `boolean | null` **Example:** ```json { "obj": [ { "id": 0, "name": null, "image_url": null, "isni": null, "code2": null, "hometown_city": null, "current_city": null, "verified": null, "band": null, "gender": null, "sp_followers": null, "sp_popularity": null, "sp_monthly_listeners": null, "deezer_fans": null, "cm_artist_rank": null, "cm_artist_score": null, "primary_genre_smart": 1, "tags": [ "" ], "spotify_artist_ids": [ "" ], "itunes_artist_ids": [ 1 ], "deezer_artist_ids": [ "" ], "amazon_artist_ids": [ "" ], "local_rank": 0, "local_rank_trend": [ {} ] } ] } ``` ### List Deezer Curators - **Method:** `GET` - **Path:** `/api/curator/deezer/lists` - **Tags:** Curator 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). #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj` (required)** `array` **Items:** - **`audiobook`** `boolean | null` - **`brand`** `boolean | null` - **`channel_subscribers`** `integer | null` - **`channel_views`** `integer | null` - **`code2`** `string | null` - **`curator_id`** `object` - **`editorial`** `boolean | null` - **`fdiff_month`** `integer | null` - **`fdiff_percent_month`** `number | null`, format: `float` - **`followers`** `integer | null` - **`indie`** `boolean | null` - **`major_label`** `boolean | null` - **`num_playlists`** `integer | null` - **`num_tracks_updated`** `integer | null` - **`num_updates`** `integer | null` - **`owner_id`** `object` - **`owner_name`** `string | null` - **`popular_indie`** `boolean | null` - **`position`** `integer | null` - **`sp_playlist_total_reach`** `integer | null` - **`submithub_id`** `string | null` - **`suspicion_score`** `number | null`, format: `float` - **`tags`** `array | null` - **`total_playlist_views`** `integer | null` - **`total_playlists`** `integer | null` - **`total_reach`** `integer | null` - **`url`** `string | null` - **`user_id`** `string | null` - **`offset`** `integer | null` - **`total`** `object` **Example:** ```json { "obj": [ { "position": null, "owner_id": 0, "owner_name": null, "url": null, "code2": null, "tags": [ null ], "num_playlists": null, "user_id": null, "sp_playlist_total_reach": null, "followers": null, "fdiff_month": null, "fdiff_percent_month": null, "submithub_id": null, "num_updates": null, "num_tracks_updated": null, "editorial": null, "major_label": null, "brand": null, "popular_indie": null, "indie": null, "audiobook": null, "suspicion_score": null, "total_reach": null, "total_playlists": null, "curator_id": 0, "channel_views": null, "channel_subscribers": null, "total_playlist_views": null } ], "offset": null, "total": 1 } ``` ### List iTunes Curators - **Method:** `GET` - **Path:** `/api/curator/itunes/lists` - **Tags:** Curator 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. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj` (required)** `array` **Items:** - **`audiobook`** `boolean | null` - **`brand`** `boolean | null` - **`channel_subscribers`** `integer | null` - **`channel_views`** `integer | null` - **`code2`** `string | null` - **`curator_id`** `object` - **`editorial`** `boolean | null` - **`fdiff_month`** `integer | null` - **`fdiff_percent_month`** `number | null`, format: `float` - **`followers`** `integer | null` - **`indie`** `boolean | null` - **`major_label`** `boolean | null` - **`num_playlists`** `integer | null` - **`num_tracks_updated`** `integer | null` - **`num_updates`** `integer | null` - **`owner_id`** `object` - **`owner_name`** `string | null` - **`popular_indie`** `boolean | null` - **`position`** `integer | null` - **`sp_playlist_total_reach`** `integer | null` - **`submithub_id`** `string | null` - **`suspicion_score`** `number | null`, format: `float` - **`tags`** `array | null` - **`total_playlist_views`** `integer | null` - **`total_playlists`** `integer | null` - **`total_reach`** `integer | null` - **`url`** `string | null` - **`user_id`** `string | null` - **`offset`** `integer | null` - **`total`** `object` **Example:** ```json { "obj": [ { "position": null, "owner_id": 0, "owner_name": null, "url": null, "code2": null, "tags": [ null ], "num_playlists": null, "user_id": null, "sp_playlist_total_reach": null, "followers": null, "fdiff_month": null, "fdiff_percent_month": null, "submithub_id": null, "num_updates": null, "num_tracks_updated": null, "editorial": null, "major_label": null, "brand": null, "popular_indie": null, "indie": null, "audiobook": null, "suspicion_score": null, "total_reach": null, "total_playlists": null, "curator_id": 0, "channel_views": null, "channel_subscribers": null, "total_playlist_views": null } ], "offset": null, "total": 1 } ``` ### List Apple Music Curators - **Method:** `GET` - **Path:** `/api/curator/applemusic/lists` - **Tags:** Curator 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. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj` (required)** `array` **Items:** - **`audiobook`** `boolean | null` - **`brand`** `boolean | null` - **`channel_subscribers`** `integer | null` - **`channel_views`** `integer | null` - **`code2`** `string | null` - **`curator_id`** `object` - **`editorial`** `boolean | null` - **`fdiff_month`** `integer | null` - **`fdiff_percent_month`** `number | null`, format: `float` - **`followers`** `integer | null` - **`indie`** `boolean | null` - **`major_label`** `boolean | null` - **`num_playlists`** `integer | null` - **`num_tracks_updated`** `integer | null` - **`num_updates`** `integer | null` - **`owner_id`** `object` - **`owner_name`** `string | null` - **`popular_indie`** `boolean | null` - **`position`** `integer | null` - **`sp_playlist_total_reach`** `integer | null` - **`submithub_id`** `string | null` - **`suspicion_score`** `number | null`, format: `float` - **`tags`** `array | null` - **`total_playlist_views`** `integer | null` - **`total_playlists`** `integer | null` - **`total_reach`** `integer | null` - **`url`** `string | null` - **`user_id`** `string | null` - **`offset`** `integer | null` - **`total`** `object` **Example:** ```json { "obj": [ { "position": null, "owner_id": 0, "owner_name": null, "url": null, "code2": null, "tags": [ null ], "num_playlists": null, "user_id": null, "sp_playlist_total_reach": null, "followers": null, "fdiff_month": null, "fdiff_percent_month": null, "submithub_id": null, "num_updates": null, "num_tracks_updated": null, "editorial": null, "major_label": null, "brand": null, "popular_indie": null, "indie": null, "audiobook": null, "suspicion_score": null, "total_reach": null, "total_playlists": null, "curator_id": 0, "channel_views": null, "channel_subscribers": null, "total_playlist_views": null } ], "offset": null, "total": 1 } ``` ### List Spotify Curators - **Method:** `GET` - **Path:** `/api/curator/spotify/lists` - **Tags:** Curator 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). #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj` (required)** `array` **Items:** - **`audiobook`** `boolean | null` - **`brand`** `boolean | null` - **`channel_subscribers`** `integer | null` - **`channel_views`** `integer | null` - **`code2`** `string | null` - **`curator_id`** `object` - **`editorial`** `boolean | null` - **`fdiff_month`** `integer | null` - **`fdiff_percent_month`** `number | null`, format: `float` - **`followers`** `integer | null` - **`indie`** `boolean | null` - **`major_label`** `boolean | null` - **`num_playlists`** `integer | null` - **`num_tracks_updated`** `integer | null` - **`num_updates`** `integer | null` - **`owner_id`** `object` - **`owner_name`** `string | null` - **`popular_indie`** `boolean | null` - **`position`** `integer | null` - **`sp_playlist_total_reach`** `integer | null` - **`submithub_id`** `string | null` - **`suspicion_score`** `number | null`, format: `float` - **`tags`** `array | null` - **`total_playlist_views`** `integer | null` - **`total_playlists`** `integer | null` - **`total_reach`** `integer | null` - **`url`** `string | null` - **`user_id`** `string | null` - **`offset`** `integer | null` - **`total`** `object` **Example:** ```json { "obj": [ { "position": null, "owner_id": 0, "owner_name": null, "url": null, "code2": null, "tags": [ null ], "num_playlists": null, "user_id": null, "sp_playlist_total_reach": null, "followers": null, "fdiff_month": null, "fdiff_percent_month": null, "submithub_id": null, "num_updates": null, "num_tracks_updated": null, "editorial": null, "major_label": null, "brand": null, "popular_indie": null, "indie": null, "audiobook": null, "suspicion_score": null, "total_reach": null, "total_playlists": null, "curator_id": 0, "channel_views": null, "channel_subscribers": null, "total_playlist_views": null } ], "offset": null, "total": 1 } ``` ### List YouTube Curators - **Method:** `GET` - **Path:** `/api/curator/youtube/lists` - **Tags:** Curator 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). #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj` (required)** `array` **Items:** - **`audiobook`** `boolean | null` - **`brand`** `boolean | null` - **`channel_subscribers`** `integer | null` - **`channel_views`** `integer | null` - **`code2`** `string | null` - **`curator_id`** `object` - **`editorial`** `boolean | null` - **`fdiff_month`** `integer | null` - **`fdiff_percent_month`** `number | null`, format: `float` - **`followers`** `integer | null` - **`indie`** `boolean | null` - **`major_label`** `boolean | null` - **`num_playlists`** `integer | null` - **`num_tracks_updated`** `integer | null` - **`num_updates`** `integer | null` - **`owner_id`** `object` - **`owner_name`** `string | null` - **`popular_indie`** `boolean | null` - **`position`** `integer | null` - **`sp_playlist_total_reach`** `integer | null` - **`submithub_id`** `string | null` - **`suspicion_score`** `number | null`, format: `float` - **`tags`** `array | null` - **`total_playlist_views`** `integer | null` - **`total_playlists`** `integer | null` - **`total_reach`** `integer | null` - **`url`** `string | null` - **`user_id`** `string | null` - **`offset`** `integer | null` - **`total`** `object` **Example:** ```json { "obj": [ { "position": null, "owner_id": 0, "owner_name": null, "url": null, "code2": null, "tags": [ null ], "num_playlists": null, "user_id": null, "sp_playlist_total_reach": null, "followers": null, "fdiff_month": null, "fdiff_percent_month": null, "submithub_id": null, "num_updates": null, "num_tracks_updated": null, "editorial": null, "major_label": null, "brand": null, "popular_indie": null, "indie": null, "audiobook": null, "suspicion_score": null, "total_reach": null, "total_playlists": null, "curator_id": 0, "channel_views": null, "channel_subscribers": null, "total_playlist_views": null } ], "offset": null, "total": 1 } ``` ### List Amazon Curators - **Method:** `GET` - **Path:** `/api/curator/amazon/lists` - **Tags:** Curator 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). #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj` (required)** `array` **Items:** - **`audiobook`** `boolean | null` - **`brand`** `boolean | null` - **`channel_subscribers`** `integer | null` - **`channel_views`** `integer | null` - **`code2`** `string | null` - **`curator_id`** `object` - **`editorial`** `boolean | null` - **`fdiff_month`** `integer | null` - **`fdiff_percent_month`** `number | null`, format: `float` - **`followers`** `integer | null` - **`indie`** `boolean | null` - **`major_label`** `boolean | null` - **`num_playlists`** `integer | null` - **`num_tracks_updated`** `integer | null` - **`num_updates`** `integer | null` - **`owner_id`** `object` - **`owner_name`** `string | null` - **`popular_indie`** `boolean | null` - **`position`** `integer | null` - **`sp_playlist_total_reach`** `integer | null` - **`submithub_id`** `string | null` - **`suspicion_score`** `number | null`, format: `float` - **`tags`** `array | null` - **`total_playlist_views`** `integer | null` - **`total_playlists`** `integer | null` - **`total_reach`** `integer | null` - **`url`** `string | null` - **`user_id`** `string | null` - **`offset`** `integer | null` - **`total`** `object` **Example:** ```json { "obj": [ { "position": null, "owner_id": 0, "owner_name": null, "url": null, "code2": null, "tags": [ null ], "num_playlists": null, "user_id": null, "sp_playlist_total_reach": null, "followers": null, "fdiff_month": null, "fdiff_percent_month": null, "submithub_id": null, "num_updates": null, "num_tracks_updated": null, "editorial": null, "major_label": null, "brand": null, "popular_indie": null, "indie": null, "audiobook": null, "suspicion_score": null, "total_reach": null, "total_playlists": null, "curator_id": 0, "channel_views": null, "channel_subscribers": null, "total_playlist_views": null } ], "offset": null, "total": 1 } ``` ### List Curators by Platform - **Method:** `GET` - **Path:** `/api/curator/{platform}/lists` - **Tags:** Curator 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). This catch-all endpoint returns HTTP 400 when `platform` is not one of `applemusic`, `deezer`, `itunes`, `spotify`, `youtube`, `amazon`. For valid platforms, use the platform-specific list route (e.g. `/api/curator/spotify/lists`). #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj` (required)** `array` **Items:** - **`audiobook`** `boolean | null` - **`brand`** `boolean | null` - **`channel_subscribers`** `integer | null` - **`channel_views`** `integer | null` - **`code2`** `string | null` - **`curator_id`** `object` - **`editorial`** `boolean | null` - **`fdiff_month`** `integer | null` - **`fdiff_percent_month`** `number | null`, format: `float` - **`followers`** `integer | null` - **`indie`** `boolean | null` - **`major_label`** `boolean | null` - **`num_playlists`** `integer | null` - **`num_tracks_updated`** `integer | null` - **`num_updates`** `integer | null` - **`owner_id`** `object` - **`owner_name`** `string | null` - **`popular_indie`** `boolean | null` - **`position`** `integer | null` - **`sp_playlist_total_reach`** `integer | null` - **`submithub_id`** `string | null` - **`suspicion_score`** `number | null`, format: `float` - **`tags`** `array | null` - **`total_playlist_views`** `integer | null` - **`total_playlists`** `integer | null` - **`total_reach`** `integer | null` - **`url`** `string | null` - **`user_id`** `string | null` - **`offset`** `integer | null` - **`total`** `object` **Example:** ```json { "obj": [ { "position": null, "owner_id": 0, "owner_name": null, "url": null, "code2": null, "tags": [ null ], "num_playlists": null, "user_id": null, "sp_playlist_total_reach": null, "followers": null, "fdiff_month": null, "fdiff_percent_month": null, "submithub_id": null, "num_updates": null, "num_tracks_updated": null, "editorial": null, "major_label": null, "brand": null, "popular_indie": null, "indie": null, "audiobook": null, "suspicion_score": null, "total_reach": null, "total_playlists": null, "curator_id": 0, "channel_views": null, "channel_subscribers": null, "total_playlist_views": null } ], "offset": null, "total": 1 } ``` ### Get Curator Metadata - **Method:** `GET` - **Path:** `/api/curator/{platform}/{id}` - **Tags:** Curator Get a curator's metadata (name, image, tags, cross-platform social stats) by `platform` and Chartmetric `id`. Supported platforms: `spotify`, `applemusic`, `deezer`, `amazon`, `youtube`. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj` (required)** `object` - **`id` (required)** `object` - **`cm_statistics`** `object | null` - **`max_sp_playlist_followers`** `integer | null` - **`num_de_playlists`** `integer | null` - **`num_itunes_playlists`** `integer | null` - **`num_sp_playlists`** `integer | null` - **`sp_followers`** `integer | null` - **`sp_playlist_total_reach`** `integer | null` - **`code2`** `string | null` - **`description`** `string | null` - **`facebook_fans`** `integer | null` - **`facebook_followers`** `integer | null` - **`groover_url`** `string | null` - **`image_url`** `string | null` - **`instagram_followers`** `object` - **`last_updated`** `string | null`, format: `date-time` - **`name`** `string | null` - **`num_itunes_playlists`** `integer | null` - **`soundcloud_followers`** `integer | null` - **`spotifySocialUrls`** `array | null` - **`storefronts`** `string | null` - **`submithub_id`** `string | null` - **`tag_ids`** `array | null` - **`tag_names`** `array | null` - **`tags`** `array | null` - **`tiktok_followers`** `integer | null` - **`tiktok_likes`** `object` - **`twitter_followers`** `integer | null` - **`twitter_retweets`** `integer | null` - **`user_id`** `object` - **`youtube_subscribers`** `integer | null` - **`youtube_views`** `object` **Example:** ```json { "obj": { "id": 0, "user_id": "", "name": null, "description": null, "image_url": null, "code2": null, "submithub_id": null, "last_updated": null, "tag_ids": [ null ], "tag_names": [ null ], "groover_url": null, "cm_statistics": { "num_sp_playlists": null, "sp_followers": null, "max_sp_playlist_followers": null, "sp_playlist_total_reach": null, "num_itunes_playlists": null, "num_de_playlists": null }, "tags": [ { "id": 0, "name": "" } ], "instagram_followers": 0, "soundcloud_followers": null, "facebook_fans": null, "facebook_followers": null, "youtube_views": 0, "youtube_subscribers": null, "twitter_followers": null, "twitter_retweets": null, "tiktok_likes": 0, "tiktok_followers": null, "spotifySocialUrls": [ {} ], "storefronts": null, "num_itunes_playlists": null } } ``` ### List Curator Playlists - **Method:** `GET` - **Path:** `/api/curator/{platform}/{id}/playlists` - **Tags:** Curator 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`. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`data` (required)** `array` **Items:** - **`id` (required)** `object` - **`active_ratio`** `number | null`, format: `float` - **`catalog`** `string | null` - **`code2`** `string | null` - **`description`** `string | null` - **`fdiff_month`** `integer | null` - **`fdiff_week`** `integer | null` - **`followers`** `integer | null` - **`image_url`** `string | null` - **`last_updated`** `string | null`, format: `date-time` - **`name`** `string | null` - **`num_track`** `object` - **`official`** `boolean | null` - **`owner_id`** `object` - **`owner_name`** `string | null` - **`personalized`** `boolean | null` - **`playlist_id`** `string | null` - **`sys_last_updated`** `string | null`, format: `date-time` - **`tags`** `array | null` - **`user_id`** `object` - **`length` (required)** `integer` - **`total_length`** `object` **Example:** ```json { "total_length": 1, "length": 0, "data": [ { "id": 0, "name": null, "playlist_id": null, "description": null, "image_url": null, "sys_last_updated": null, "last_updated": null, "personalized": null, "code2": null, "owner_name": null, "owner_id": 0, "user_id": "", "official": null, "tags": [ { "id": 0, "name": "" } ], "followers": null, "num_track": 1, "fdiff_week": null, "fdiff_month": null, "catalog": null, "active_ratio": null } ] } ``` ### List Curator Social / Streaming URLs - **Method:** `GET` - **Path:** `/api/curator/{platform}/{id}/urls` - **Tags:** Curator 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. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj` (required)** `array` **Items:** - **`domain` (required)** `string` - **`url`** `object` **Example:** ```json { "obj": [ { "domain": "", "url": "" } ] } ``` ### Get Curator Fan Metrics - **Method:** `GET` - **Path:** `/api/curator/{platform}/{id}/stat/{source}` - **Tags:** Curator Time-series fan metrics for a curator from a given `source` (spotify, facebook, twitter, youtube\_channel, instagram, tiktok). Pass `field` to request a single metric (e.g. `followers`, `likes`) or omit it to receive defaults: spotify → `followers`; facebook → `followers`, `likes`, `talks`; twitter → `followers`; youtube\_channel → `subscribers`, `views`, `videos`; instagram → `followers`; tiktok → `followers`, `likes`. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj`** `object` - **`followers`** `array` **Items:** - **`daily_diff`** `number | null`, format: `float` - **`diff`** `number | null`, format: `float` - **`extrapolated`** `boolean | null` - **`flags`** `boolean | null` - **`interpolated`** `boolean | null` - **`monthly_diff`** `number | null`, format: `float` - **`monthly_diff_percent`** `number | null`, format: `float` - **`timestp`** `string | null`, format: `date-time` - **`value`** `number | null`, format: `float` - **`weekly_diff`** `number | null`, format: `float` - **`weekly_diff_percent`** `number | null`, format: `float` - **`followers_to_listeners_ratio`** `array` **Items:** - **`daily_diff`** `number | null`, format: `float` - **`diff`** `number | null`, format: `float` - **`extrapolated`** `boolean | null` - **`flags`** `boolean | null` - **`interpolated`** `boolean | null` - **`monthly_diff`** `number | null`, format: `float` - **`monthly_diff_percent`** `number | null`, format: `float` - **`timestp`** `string | null`, format: `date-time` - **`value`** `number | null`, format: `float` - **`weekly_diff`** `number | null`, format: `float` - **`weekly_diff_percent`** `number | null`, format: `float` - **`likes`** `array` **Items:** - **`daily_diff`** `number | null`, format: `float` - **`diff`** `number | null`, format: `float` - **`extrapolated`** `boolean | null` - **`flags`** `boolean | null` - **`interpolated`** `boolean | null` - **`monthly_diff`** `number | null`, format: `float` - **`monthly_diff_percent`** `number | null`, format: `float` - **`timestp`** `string | null`, format: `date-time` - **`value`** `number | null`, format: `float` - **`weekly_diff`** `number | null`, format: `float` - **`weekly_diff_percent`** `number | null`, format: `float` - **`link`** `string | null` - **`listeners`** `array` **Items:** - **`daily_diff`** `number | null`, format: `float` - **`diff`** `number | null`, format: `float` - **`extrapolated`** `boolean | null` - **`flags`** `boolean | null` - **`interpolated`** `boolean | null` - **`monthly_diff`** `number | null`, format: `float` - **`monthly_diff_percent`** `number | null`, format: `float` - **`timestp`** `string | null`, format: `date-time` - **`value`** `number | null`, format: `float` - **`weekly_diff`** `number | null`, format: `float` - **`weekly_diff_percent`** `number | null`, format: `float` - **`popularity`** `array` **Items:** - **`daily_diff`** `number | null`, format: `float` - **`diff`** `number | null`, format: `float` - **`extrapolated`** `boolean | null` - **`flags`** `boolean | null` - **`interpolated`** `boolean | null` - **`monthly_diff`** `number | null`, format: `float` - **`monthly_diff_percent`** `number | null`, format: `float` - **`timestp`** `string | null`, format: `date-time` - **`value`** `number | null`, format: `float` - **`weekly_diff`** `number | null`, format: `float` - **`weekly_diff_percent`** `number | null`, format: `float` - **`subscribers`** `array` **Items:** - **`daily_diff`** `number | null`, format: `float` - **`diff`** `number | null`, format: `float` - **`extrapolated`** `boolean | null` - **`flags`** `boolean | null` - **`interpolated`** `boolean | null` - **`monthly_diff`** `number | null`, format: `float` - **`monthly_diff_percent`** `number | null`, format: `float` - **`timestp`** `string | null`, format: `date-time` - **`value`** `number | null`, format: `float` - **`weekly_diff`** `number | null`, format: `float` - **`weekly_diff_percent`** `number | null`, format: `float` - **`talks`** `array` **Items:** - **`daily_diff`** `number | null`, format: `float` - **`diff`** `number | null`, format: `float` - **`extrapolated`** `boolean | null` - **`flags`** `boolean | null` - **`interpolated`** `boolean | null` - **`monthly_diff`** `number | null`, format: `float` - **`monthly_diff_percent`** `number | null`, format: `float` - **`timestp`** `string | null`, format: `date-time` - **`value`** `number | null`, format: `float` - **`weekly_diff`** `number | null`, format: `float` - **`weekly_diff_percent`** `number | null`, format: `float` - **`videos`** `array` **Items:** - **`daily_diff`** `number | null`, format: `float` - **`diff`** `number | null`, format: `float` - **`extrapolated`** `boolean | null` - **`flags`** `boolean | null` - **`interpolated`** `boolean | null` - **`monthly_diff`** `number | null`, format: `float` - **`monthly_diff_percent`** `number | null`, format: `float` - **`timestp`** `string | null`, format: `date-time` - **`value`** `number | null`, format: `float` - **`weekly_diff`** `number | null`, format: `float` - **`weekly_diff_percent`** `number | null`, format: `float` - **`views`** `array` **Items:** - **`daily_diff`** `number | null`, format: `float` - **`diff`** `number | null`, format: `float` - **`extrapolated`** `boolean | null` - **`flags`** `boolean | null` - **`interpolated`** `boolean | null` - **`monthly_diff`** `number | null`, format: `float` - **`monthly_diff_percent`** `number | null`, format: `float` - **`timestp`** `string | null`, format: `date-time` - **`value`** `number | null`, format: `float` - **`weekly_diff`** `number | null`, format: `float` - **`weekly_diff_percent`** `number | null`, format: `float` **Example:** ```json { "obj": { "link": null, "followers": [ { "value": null, "timestp": null, "flags": null, "diff": null, "weekly_diff": null, "weekly_diff_percent": null, "monthly_diff": null, "monthly_diff_percent": null, "daily_diff": null, "interpolated": null, "extrapolated": null } ], "popularity": [ { "value": null, "timestp": null, "flags": null, "diff": null, "weekly_diff": null, "weekly_diff_percent": null, "monthly_diff": null, "monthly_diff_percent": null, "daily_diff": null, "interpolated": null, "extrapolated": null } ], "listeners": [ { "value": null, "timestp": null, "flags": null, "diff": null, "weekly_diff": null, "weekly_diff_percent": null, "monthly_diff": null, "monthly_diff_percent": null, "daily_diff": null, "interpolated": null, "extrapolated": null } ], "followers_to_listeners_ratio": [ { "value": null, "timestp": null, "flags": null, "diff": null, "weekly_diff": null, "weekly_diff_percent": null, "monthly_diff": null, "monthly_diff_percent": null, "daily_diff": null, "interpolated": null, "extrapolated": null } ], "likes": [ { "value": null, "timestp": null, "flags": null, "diff": null, "weekly_diff": null, "weekly_diff_percent": null, "monthly_diff": null, "monthly_diff_percent": null, "daily_diff": null, "interpolated": null, "extrapolated": null } ], "talks": [ { "value": null, "timestp": null, "flags": null, "diff": null, "weekly_diff": null, "weekly_diff_percent": null, "monthly_diff": null, "monthly_diff_percent": null, "daily_diff": null, "interpolated": null, "extrapolated": null } ], "subscribers": [ { "value": null, "timestp": null, "flags": null, "diff": null, "weekly_diff": null, "weekly_diff_percent": null, "monthly_diff": null, "monthly_diff_percent": null, "daily_diff": null, "interpolated": null, "extrapolated": null } ], "views": [ { "value": null, "timestp": null, "flags": null, "diff": null, "weekly_diff": null, "weekly_diff_percent": null, "monthly_diff": null, "monthly_diff_percent": null, "daily_diff": null, "interpolated": null, "extrapolated": null } ], "videos": [ { "value": null, "timestp": null, "flags": null, "diff": null, "weekly_diff": null, "weekly_diff_percent": null, "monthly_diff": null, "monthly_diff_percent": null, "daily_diff": null, "interpolated": null, "extrapolated": null } ] } } ``` ### List Amazon Playlists - **Method:** `GET` - **Path:** `/api/playlist/amazon/lists` - **Tags:** Playlist 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. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj` (required)** `array` **Items:** - **`id` (required)** `object` - **`active_ratio`** `number | null`, format: `float` - **`activities`** `array | null` - **`activity_smart_ordered`** `array | null` - **`artist_permalink`** `string | null` - **`catalog`** `string | null` - **`chart`** `boolean` - **`chart_ranks`** `array` **Items:** - **`code2`** `string | null` - **`code2s`** `array` **Items:** `string` - **`curator_id`** `object` - **`description`** `string | null` - **`editorial`** `boolean` - **`editorial_brand`** `boolean` - **`fdiff_month`** `integer | null` - **`fdiff_percent_month`** `number | null`, format: `float` - **`fdiff_percent_week`** `number | null`, format: `float` - **`fdiff_week`** `integer | null` - **`followers`** `integer | null` - **`genre`** `string | null` - **`groover_url`** `string | null` - **`image_url`** `string | null` - **`indie_curator`** `boolean` - **`last_updated`** `object` - **`latest`** `object` - **`monthly_diff`** `object` - **`monthly_diff_percent`** `object` - **`mood_smart_ordered`** `array | null` - **`moods`** `array | null` - **`music_brand_curator`** `boolean` - **`name`** `string | null` - **`non_music_brand_curator`** `boolean` - **`num_track`** `object` - **`owner_id`** `object` - **`owner_name`** `string | null` - **`permalink`** `string | null` - **`personality_artist_curator`** `boolean` - **`personalized`** `boolean` - **`playlist_id`** `object` - **`playlist_updated`** `object` - **`position`** `integer` - **`radio`** `boolean` - **`rank`** `integer | null` - **`score_100`** `number | null`, format: `float` - **`soundcloud_artist_name`** `string | null` - **`soundcloud_updated`** `object` - **`submithub_url`** `string | null` - **`suspicion_score`** `number | null`, format: `float` - **`tag_ids`** `array | null` - **`user_id`** `string | null` - **`vdiff_month`** `integer | null` - **`vdiff_percent_month`** `number | null`, format: `float` - **`vdiff_percent_week`** `number | null`, format: `float` - **`vdiff_week`** `integer | null` - **`views`** `integer | null` - **`with_storefronts`** `boolean` - **`youtube_last_updated`** `object` - **`offset` (required)** `integer` - **`total` (required)** `integer` **Example:** ```json { "obj": [ { "position": 0, "id": 0, "name": null, "image_url": null, "description": null, "active_ratio": null, "num_track": 1, "last_updated": "", "owner_id": 1, "owner_name": null, "code2": null, "editorial": true, "genre": null, "followers": null, "fdiff_week": null, "fdiff_percent_week": null, "fdiff_month": null, "fdiff_percent_month": null, "playlist_id": 0, "user_id": null, "catalog": null, "personalized": true, "playlist_updated": "", "tag_ids": [ 0 ], "suspicion_score": null, "submithub_url": null, "groover_url": null, "score_100": null, "views": null, "vdiff_week": null, "vdiff_percent_week": null, "vdiff_month": null, "vdiff_percent_month": null, "youtube_last_updated": "", "permalink": null, "artist_permalink": null, "soundcloud_artist_name": null, "monthly_diff": null, "monthly_diff_percent": null, "latest": null, "soundcloud_updated": "", "with_storefronts": true, "code2s": [ "" ], "chart": true, "radio": true, "music_brand_curator": true, "non_music_brand_curator": true, "editorial_brand": true, "indie_curator": true, "personality_artist_curator": true, "curator_id": 0, "chart_ranks": [], "rank": null, "moods": [ { "id": 0, "name": null } ], "activities": [ { "id": 0, "name": null } ], "mood_smart_ordered": [], "activity_smart_ordered": [] } ], "offset": 0, "total": 0 } ``` ### List Itunes Playlists - **Method:** `GET` - **Path:** `/api/playlist/itunes/lists` - **Tags:** Playlist 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. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj` (required)** `array` **Items:** - **`id` (required)** `object` - **`active_ratio`** `number | null`, format: `float` - **`activities`** `array | null` - **`activity_smart_ordered`** `array | null` - **`artist_permalink`** `string | null` - **`catalog`** `string | null` - **`chart`** `boolean` - **`chart_ranks`** `array` **Items:** - **`code2`** `string | null` - **`code2s`** `array` **Items:** `string` - **`curator_id`** `object` - **`description`** `string | null` - **`editorial`** `boolean` - **`editorial_brand`** `boolean` - **`fdiff_month`** `integer | null` - **`fdiff_percent_month`** `number | null`, format: `float` - **`fdiff_percent_week`** `number | null`, format: `float` - **`fdiff_week`** `integer | null` - **`followers`** `integer | null` - **`genre`** `string | null` - **`groover_url`** `string | null` - **`image_url`** `string | null` - **`indie_curator`** `boolean` - **`last_updated`** `object` - **`latest`** `object` - **`monthly_diff`** `object` - **`monthly_diff_percent`** `object` - **`mood_smart_ordered`** `array | null` - **`moods`** `array | null` - **`music_brand_curator`** `boolean` - **`name`** `string | null` - **`non_music_brand_curator`** `boolean` - **`num_track`** `object` - **`owner_id`** `object` - **`owner_name`** `string | null` - **`permalink`** `string | null` - **`personality_artist_curator`** `boolean` - **`personalized`** `boolean` - **`playlist_id`** `object` - **`playlist_updated`** `object` - **`position`** `integer` - **`radio`** `boolean` - **`rank`** `integer | null` - **`score_100`** `number | null`, format: `float` - **`soundcloud_artist_name`** `string | null` - **`soundcloud_updated`** `object` - **`submithub_url`** `string | null` - **`suspicion_score`** `number | null`, format: `float` - **`tag_ids`** `array | null` - **`user_id`** `string | null` - **`vdiff_month`** `integer | null` - **`vdiff_percent_month`** `number | null`, format: `float` - **`vdiff_percent_week`** `number | null`, format: `float` - **`vdiff_week`** `integer | null` - **`views`** `integer | null` - **`with_storefronts`** `boolean` - **`youtube_last_updated`** `object` - **`offset` (required)** `integer` - **`total` (required)** `integer` **Example:** ```json { "obj": [ { "position": 0, "id": 0, "name": null, "image_url": null, "description": null, "active_ratio": null, "num_track": 1, "last_updated": "", "owner_id": 1, "owner_name": null, "code2": null, "editorial": true, "genre": null, "followers": null, "fdiff_week": null, "fdiff_percent_week": null, "fdiff_month": null, "fdiff_percent_month": null, "playlist_id": 0, "user_id": null, "catalog": null, "personalized": true, "playlist_updated": "", "tag_ids": [ 0 ], "suspicion_score": null, "submithub_url": null, "groover_url": null, "score_100": null, "views": null, "vdiff_week": null, "vdiff_percent_week": null, "vdiff_month": null, "vdiff_percent_month": null, "youtube_last_updated": "", "permalink": null, "artist_permalink": null, "soundcloud_artist_name": null, "monthly_diff": null, "monthly_diff_percent": null, "latest": null, "soundcloud_updated": "", "with_storefronts": true, "code2s": [ "" ], "chart": true, "radio": true, "music_brand_curator": true, "non_music_brand_curator": true, "editorial_brand": true, "indie_curator": true, "personality_artist_curator": true, "curator_id": 0, "chart_ranks": [], "rank": null, "moods": [ { "id": 0, "name": null } ], "activities": [ { "id": 0, "name": null } ], "mood_smart_ordered": [], "activity_smart_ordered": [] } ], "offset": 0, "total": 0 } ``` ### List Deezer Playlists - **Method:** `GET` - **Path:** `/api/playlist/deezer/lists` - **Tags:** Playlist 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. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj` (required)** `array` **Items:** - **`id` (required)** `object` - **`active_ratio`** `number | null`, format: `float` - **`activities`** `array | null` - **`activity_smart_ordered`** `array | null` - **`artist_permalink`** `string | null` - **`catalog`** `string | null` - **`chart`** `boolean` - **`chart_ranks`** `array` **Items:** - **`code2`** `string | null` - **`code2s`** `array` **Items:** `string` - **`curator_id`** `object` - **`description`** `string | null` - **`editorial`** `boolean` - **`editorial_brand`** `boolean` - **`fdiff_month`** `integer | null` - **`fdiff_percent_month`** `number | null`, format: `float` - **`fdiff_percent_week`** `number | null`, format: `float` - **`fdiff_week`** `integer | null` - **`followers`** `integer | null` - **`genre`** `string | null` - **`groover_url`** `string | null` - **`image_url`** `string | null` - **`indie_curator`** `boolean` - **`last_updated`** `object` - **`latest`** `object` - **`monthly_diff`** `object` - **`monthly_diff_percent`** `object` - **`mood_smart_ordered`** `array | null` - **`moods`** `array | null` - **`music_brand_curator`** `boolean` - **`name`** `string | null` - **`non_music_brand_curator`** `boolean` - **`num_track`** `object` - **`owner_id`** `object` - **`owner_name`** `string | null` - **`permalink`** `string | null` - **`personality_artist_curator`** `boolean` - **`personalized`** `boolean` - **`playlist_id`** `object` - **`playlist_updated`** `object` - **`position`** `integer` - **`radio`** `boolean` - **`rank`** `integer | null` - **`score_100`** `number | null`, format: `float` - **`soundcloud_artist_name`** `string | null` - **`soundcloud_updated`** `object` - **`submithub_url`** `string | null` - **`suspicion_score`** `number | null`, format: `float` - **`tag_ids`** `array | null` - **`user_id`** `string | null` - **`vdiff_month`** `integer | null` - **`vdiff_percent_month`** `number | null`, format: `float` - **`vdiff_percent_week`** `number | null`, format: `float` - **`vdiff_week`** `integer | null` - **`views`** `integer | null` - **`with_storefronts`** `boolean` - **`youtube_last_updated`** `object` - **`offset` (required)** `integer` - **`total` (required)** `integer` **Example:** ```json { "obj": [ { "position": 0, "id": 0, "name": null, "image_url": null, "description": null, "active_ratio": null, "num_track": 1, "last_updated": "", "owner_id": 1, "owner_name": null, "code2": null, "editorial": true, "genre": null, "followers": null, "fdiff_week": null, "fdiff_percent_week": null, "fdiff_month": null, "fdiff_percent_month": null, "playlist_id": 0, "user_id": null, "catalog": null, "personalized": true, "playlist_updated": "", "tag_ids": [ 0 ], "suspicion_score": null, "submithub_url": null, "groover_url": null, "score_100": null, "views": null, "vdiff_week": null, "vdiff_percent_week": null, "vdiff_month": null, "vdiff_percent_month": null, "youtube_last_updated": "", "permalink": null, "artist_permalink": null, "soundcloud_artist_name": null, "monthly_diff": null, "monthly_diff_percent": null, "latest": null, "soundcloud_updated": "", "with_storefronts": true, "code2s": [ "" ], "chart": true, "radio": true, "music_brand_curator": true, "non_music_brand_curator": true, "editorial_brand": true, "indie_curator": true, "personality_artist_curator": true, "curator_id": 0, "chart_ranks": [], "rank": null, "moods": [ { "id": 0, "name": null } ], "activities": [ { "id": 0, "name": null } ], "mood_smart_ordered": [], "activity_smart_ordered": [] } ], "offset": 0, "total": 0 } ``` ### List Spotify Playlists - **Method:** `GET` - **Path:** `/api/playlist/spotify/lists` - **Tags:** Playlist 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. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj` (required)** `array` **Items:** - **`id` (required)** `object` - **`active_ratio`** `number | null`, format: `float` - **`activities`** `array | null` - **`activity_smart_ordered`** `array | null` - **`artist_permalink`** `string | null` - **`catalog`** `string | null` - **`chart`** `boolean` - **`chart_ranks`** `array` **Items:** - **`code2`** `string | null` - **`code2s`** `array` **Items:** `string` - **`curator_id`** `object` - **`description`** `string | null` - **`editorial`** `boolean` - **`editorial_brand`** `boolean` - **`fdiff_month`** `integer | null` - **`fdiff_percent_month`** `number | null`, format: `float` - **`fdiff_percent_week`** `number | null`, format: `float` - **`fdiff_week`** `integer | null` - **`followers`** `integer | null` - **`genre`** `string | null` - **`groover_url`** `string | null` - **`image_url`** `string | null` - **`indie_curator`** `boolean` - **`last_updated`** `object` - **`latest`** `object` - **`monthly_diff`** `object` - **`monthly_diff_percent`** `object` - **`mood_smart_ordered`** `array | null` - **`moods`** `array | null` - **`music_brand_curator`** `boolean` - **`name`** `string | null` - **`non_music_brand_curator`** `boolean` - **`num_track`** `object` - **`owner_id`** `object` - **`owner_name`** `string | null` - **`permalink`** `string | null` - **`personality_artist_curator`** `boolean` - **`personalized`** `boolean` - **`playlist_id`** `object` - **`playlist_updated`** `object` - **`position`** `integer` - **`radio`** `boolean` - **`rank`** `integer | null` - **`score_100`** `number | null`, format: `float` - **`soundcloud_artist_name`** `string | null` - **`soundcloud_updated`** `object` - **`submithub_url`** `string | null` - **`suspicion_score`** `number | null`, format: `float` - **`tag_ids`** `array | null` - **`user_id`** `string | null` - **`vdiff_month`** `integer | null` - **`vdiff_percent_month`** `number | null`, format: `float` - **`vdiff_percent_week`** `number | null`, format: `float` - **`vdiff_week`** `integer | null` - **`views`** `integer | null` - **`with_storefronts`** `boolean` - **`youtube_last_updated`** `object` - **`offset` (required)** `integer` - **`total` (required)** `integer` **Example:** ```json { "obj": [ { "position": 0, "id": 0, "name": null, "image_url": null, "description": null, "active_ratio": null, "num_track": 1, "last_updated": "", "owner_id": 1, "owner_name": null, "code2": null, "editorial": true, "genre": null, "followers": null, "fdiff_week": null, "fdiff_percent_week": null, "fdiff_month": null, "fdiff_percent_month": null, "playlist_id": 0, "user_id": null, "catalog": null, "personalized": true, "playlist_updated": "", "tag_ids": [ 0 ], "suspicion_score": null, "submithub_url": null, "groover_url": null, "score_100": null, "views": null, "vdiff_week": null, "vdiff_percent_week": null, "vdiff_month": null, "vdiff_percent_month": null, "youtube_last_updated": "", "permalink": null, "artist_permalink": null, "soundcloud_artist_name": null, "monthly_diff": null, "monthly_diff_percent": null, "latest": null, "soundcloud_updated": "", "with_storefronts": true, "code2s": [ "" ], "chart": true, "radio": true, "music_brand_curator": true, "non_music_brand_curator": true, "editorial_brand": true, "indie_curator": true, "personality_artist_curator": true, "curator_id": 0, "chart_ranks": [], "rank": null, "moods": [ { "id": 0, "name": null } ], "activities": [ { "id": 0, "name": null } ], "mood_smart_ordered": [], "activity_smart_ordered": [] } ], "offset": 0, "total": 0 } ``` ### List Youtube Playlists - **Method:** `GET` - **Path:** `/api/playlist/youtube/lists` - **Tags:** Playlist 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. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj` (required)** `array` **Items:** - **`id` (required)** `object` - **`active_ratio`** `number | null`, format: `float` - **`activities`** `array | null` - **`activity_smart_ordered`** `array | null` - **`artist_permalink`** `string | null` - **`catalog`** `string | null` - **`chart`** `boolean` - **`chart_ranks`** `array` **Items:** - **`code2`** `string | null` - **`code2s`** `array` **Items:** `string` - **`curator_id`** `object` - **`description`** `string | null` - **`editorial`** `boolean` - **`editorial_brand`** `boolean` - **`fdiff_month`** `integer | null` - **`fdiff_percent_month`** `number | null`, format: `float` - **`fdiff_percent_week`** `number | null`, format: `float` - **`fdiff_week`** `integer | null` - **`followers`** `integer | null` - **`genre`** `string | null` - **`groover_url`** `string | null` - **`image_url`** `string | null` - **`indie_curator`** `boolean` - **`last_updated`** `object` - **`latest`** `object` - **`monthly_diff`** `object` - **`monthly_diff_percent`** `object` - **`mood_smart_ordered`** `array | null` - **`moods`** `array | null` - **`music_brand_curator`** `boolean` - **`name`** `string | null` - **`non_music_brand_curator`** `boolean` - **`num_track`** `object` - **`owner_id`** `object` - **`owner_name`** `string | null` - **`permalink`** `string | null` - **`personality_artist_curator`** `boolean` - **`personalized`** `boolean` - **`playlist_id`** `object` - **`playlist_updated`** `object` - **`position`** `integer` - **`radio`** `boolean` - **`rank`** `integer | null` - **`score_100`** `number | null`, format: `float` - **`soundcloud_artist_name`** `string | null` - **`soundcloud_updated`** `object` - **`submithub_url`** `string | null` - **`suspicion_score`** `number | null`, format: `float` - **`tag_ids`** `array | null` - **`user_id`** `string | null` - **`vdiff_month`** `integer | null` - **`vdiff_percent_month`** `number | null`, format: `float` - **`vdiff_percent_week`** `number | null`, format: `float` - **`vdiff_week`** `integer | null` - **`views`** `integer | null` - **`with_storefronts`** `boolean` - **`youtube_last_updated`** `object` - **`offset` (required)** `integer` - **`total` (required)** `integer` **Example:** ```json { "obj": [ { "position": 0, "id": 0, "name": null, "image_url": null, "description": null, "active_ratio": null, "num_track": 1, "last_updated": "", "owner_id": 1, "owner_name": null, "code2": null, "editorial": true, "genre": null, "followers": null, "fdiff_week": null, "fdiff_percent_week": null, "fdiff_month": null, "fdiff_percent_month": null, "playlist_id": 0, "user_id": null, "catalog": null, "personalized": true, "playlist_updated": "", "tag_ids": [ 0 ], "suspicion_score": null, "submithub_url": null, "groover_url": null, "score_100": null, "views": null, "vdiff_week": null, "vdiff_percent_week": null, "vdiff_month": null, "vdiff_percent_month": null, "youtube_last_updated": "", "permalink": null, "artist_permalink": null, "soundcloud_artist_name": null, "monthly_diff": null, "monthly_diff_percent": null, "latest": null, "soundcloud_updated": "", "with_storefronts": true, "code2s": [ "" ], "chart": true, "radio": true, "music_brand_curator": true, "non_music_brand_curator": true, "editorial_brand": true, "indie_curator": true, "personality_artist_curator": true, "curator_id": 0, "chart_ranks": [], "rank": null, "moods": [ { "id": 0, "name": null } ], "activities": [ { "id": 0, "name": null } ], "mood_smart_ordered": [], "activity_smart_ordered": [] } ], "offset": 0, "total": 0 } ``` ### List Soundcloud Playlists - **Method:** `GET` - **Path:** `/api/playlist/soundcloud/lists` - **Tags:** Playlist 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. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj` (required)** `array` **Items:** - **`id` (required)** `object` - **`active_ratio`** `number | null`, format: `float` - **`activities`** `array | null` - **`activity_smart_ordered`** `array | null` - **`artist_permalink`** `string | null` - **`catalog`** `string | null` - **`chart`** `boolean` - **`chart_ranks`** `array` **Items:** - **`code2`** `string | null` - **`code2s`** `array` **Items:** `string` - **`curator_id`** `object` - **`description`** `string | null` - **`editorial`** `boolean` - **`editorial_brand`** `boolean` - **`fdiff_month`** `integer | null` - **`fdiff_percent_month`** `number | null`, format: `float` - **`fdiff_percent_week`** `number | null`, format: `float` - **`fdiff_week`** `integer | null` - **`followers`** `integer | null` - **`genre`** `string | null` - **`groover_url`** `string | null` - **`image_url`** `string | null` - **`indie_curator`** `boolean` - **`last_updated`** `object` - **`latest`** `object` - **`monthly_diff`** `object` - **`monthly_diff_percent`** `object` - **`mood_smart_ordered`** `array | null` - **`moods`** `array | null` - **`music_brand_curator`** `boolean` - **`name`** `string | null` - **`non_music_brand_curator`** `boolean` - **`num_track`** `object` - **`owner_id`** `object` - **`owner_name`** `string | null` - **`permalink`** `string | null` - **`personality_artist_curator`** `boolean` - **`personalized`** `boolean` - **`playlist_id`** `object` - **`playlist_updated`** `object` - **`position`** `integer` - **`radio`** `boolean` - **`rank`** `integer | null` - **`score_100`** `number | null`, format: `float` - **`soundcloud_artist_name`** `string | null` - **`soundcloud_updated`** `object` - **`submithub_url`** `string | null` - **`suspicion_score`** `number | null`, format: `float` - **`tag_ids`** `array | null` - **`user_id`** `string | null` - **`vdiff_month`** `integer | null` - **`vdiff_percent_month`** `number | null`, format: `float` - **`vdiff_percent_week`** `number | null`, format: `float` - **`vdiff_week`** `integer | null` - **`views`** `integer | null` - **`with_storefronts`** `boolean` - **`youtube_last_updated`** `object` - **`offset` (required)** `integer` - **`total` (required)** `integer` **Example:** ```json { "obj": [ { "position": 0, "id": 0, "name": null, "image_url": null, "description": null, "active_ratio": null, "num_track": 1, "last_updated": "", "owner_id": 1, "owner_name": null, "code2": null, "editorial": true, "genre": null, "followers": null, "fdiff_week": null, "fdiff_percent_week": null, "fdiff_month": null, "fdiff_percent_month": null, "playlist_id": 0, "user_id": null, "catalog": null, "personalized": true, "playlist_updated": "", "tag_ids": [ 0 ], "suspicion_score": null, "submithub_url": null, "groover_url": null, "score_100": null, "views": null, "vdiff_week": null, "vdiff_percent_week": null, "vdiff_month": null, "vdiff_percent_month": null, "youtube_last_updated": "", "permalink": null, "artist_permalink": null, "soundcloud_artist_name": null, "monthly_diff": null, "monthly_diff_percent": null, "latest": null, "soundcloud_updated": "", "with_storefronts": true, "code2s": [ "" ], "chart": true, "radio": true, "music_brand_curator": true, "non_music_brand_curator": true, "editorial_brand": true, "indie_curator": true, "personality_artist_curator": true, "curator_id": 0, "chart_ranks": [], "rank": null, "moods": [ { "id": 0, "name": null } ], "activities": [ { "id": 0, "name": null } ], "mood_smart_ordered": [], "activity_smart_ordered": [] } ], "offset": 0, "total": 0 } ``` ### Playlist List (unknown platform - 400) - **Method:** `GET` - **Path:** `/api/playlist/{platform}/lists` - **Tags:** Playlist Fallback route for unsupported `platform` values. Returns a 400 with an `error` message. Documented for completeness — the 200 shape is only defined on the six platform-specific `/api/playlist/{platform}/lists` routes. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`error` (required)** `string` **Example:** ```json { "error": "" } ``` ### Get Playlist Metadata - **Method:** `GET` - **Path:** `/api/playlist/{platform}/{id}` - **Tags:** Playlist Fetch metadata for a Chartmetric playlist on a streaming platform. Response shape varies slightly per platform; follower counts may exceed the 32-bit range. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj`** `object | null` - **`id` (required)** `integer` - **`active_ratio`** `number | null`, format: `float` - **`activities`** `array | null` - **`catalog`** `string | null` - **`code2`** `string | null` - **`description`** `string | null` - **`editorial`** `boolean` - **`fdiff_month`** `integer | null` - **`fdiff_week`** `integer | null` - **`followers`** `integer | null` - **`genres`** `array | null` - **`image_url`** `string | null` - **`last_updated`** `object` - **`likes`** `integer | null` - **`moods`** `array | null` - **`name`** `string | null` - **`new_sp_id`** `string | null` - **`num_track`** `object` - **`owner_id`** `object` - **`owner_name`** `string | null` - **`personalized`** `boolean` - **`playlist_id`** `string | null` - **`sys_last_updated`** `object` - **`tags`** `array | null` - **`user_id`** `object` **Example:** ```json { "obj": { "id": 0, "name": null, "playlist_id": null, "description": null, "image_url": null, "sys_last_updated": "", "last_updated": "", "personalized": true, "code2": null, "owner_name": null, "owner_id": 1, "user_id": 1, "editorial": true, "tags": [ { "id": 0, "name": "", "source": null, "type": null, "url": null, "created_at": null, "modified_at": null } ], "followers": null, "likes": null, "num_track": 1, "fdiff_week": null, "fdiff_month": null, "catalog": null, "active_ratio": null, "new_sp_id": null, "moods": [ { "id": 0, "name": null } ], "activities": [ { "id": 0, "name": null } ], "genres": [ { "id": 0, "name": null } ] } } ``` ### Get Playlist Stats Over Time - **Method:** `GET` - **Path:** `/api/playlist/{platform}/{id}/stats` - **Tags:** Playlist Time series of playlist audience stats (Spotify followers / Deezer fans / YouTube views / SoundCloud likes) over a date range. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj` (required)** `array` **Items:** - **`timestp` (required)** `object` - **`value` (required)** `integer` - **`daily_diff`** `integer | null` - **`extrapolated`** `boolean` - **`flags`** `boolean` - **`id`** `integer` - **`interpolated`** `boolean` - **`monthly_diff`** `integer | null` - **`monthly_diff_percent`** `number | null`, format: `float` - **`weekly_diff`** `integer | null` - **`weekly_diff_percent`** `number | null`, format: `float` **Example:** ```json { "obj": [ { "id": 0, "value": 0, "timestp": "", "daily_diff": null, "weekly_diff": null, "weekly_diff_percent": null, "monthly_diff": null, "monthly_diff_percent": null, "interpolated": true, "extrapolated": true, "flags": true } ] } ``` ### Get Playlist Snapshot on a Date - **Method:** `GET` - **Path:** `/api/playlist/{platform}/{id}/snapshot` - **Tags:** Playlist Returns the tracks that were on the playlist on the given `date`, each enriched with basic track info (name, ISRC, artists, album metadata). #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj` (required)** `array` **Items:** - **`added_at`** `object` - **`album_ids`** `array | null` - **`album_label`** `array | null` - **`album_names`** `array | null` - **`album_upc`** `array | null` - **`artist_covers`** `array | null` - **`artist_images`** `array | null` - **`artist_names`** `array | null` - **`cm_artist`** `array | null` - **`cm_track`** `integer` - **`code2s`** `array | null` - **`id`** `integer` - **`image_url`** `string | null` - **`isrc`** `string | null` - **`name`** `string | null` - **`position`** `integer | null` - **`preview_url`** `string | null` - **`release_dates`** `array | null` - **`removed_at`** `object` - **`spotify_album_id`** `string | null` - **`spotify_album_ids`** `array | null` - **`spotify_artist_ids`** `array | null` - **`spotify_artist_names`** `array | null` - **`spotify_duration_ms`** `integer | null` - **`spotify_popularity`** `integer | null` - **`spotify_track_id`** `string | null` - **`spotify_track_ids`** `array | null` - **`storefront`** `string | null` - **`track_genre`** `string | null` - **`track_id`** `integer` **Example:** ```json { "obj": [ { "track_id": 0, "id": 0, "added_at": "", "removed_at": "", "position": null, "name": null, "isrc": null, "spotify_track_id": null, "spotify_album_id": null, "image_url": null, "spotify_popularity": null, "cm_track": 0, "spotify_artist_names": [ null ], "track_genre": null, "cm_artist": [ 0 ], "artist_names": [ null ], "code2s": [ null ], "artist_images": [ null ], "artist_covers": [ null ], "spotify_artist_ids": [ null ], "spotify_track_ids": [ null ], "spotify_album_ids": [ null ], "spotify_duration_ms": null, "album_ids": [ 0 ], "album_names": [ null ], "album_upc": [ null ], "album_label": [ null ], "release_dates": [ "" ], "preview_url": null, "storefront": null } ] } ``` ### Get Similar Playlists - **Method:** `GET` - **Path:** `/api/playlist/{platform}/{id}/similarplaylists` - **Tags:** Playlist Return playlists similar to the target playlist on the given platform (Spotify or SoundCloud), with overlap flags for shared moods/genres. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj` (required)** `array` **Items:** - **`id` (required)** `object` - **`followers`** `integer | null` - **`genre`** `string | null` - **`genres`** `array | null` - **`image_url`** `string | null` - **`isOverlappingGenre`** `boolean` - **`likes`** `integer | null` - **`moods`** `array | null` - **`name`** `string | null` - **`owner_id`** `object` - **`owner_name`** `string | null` - **`owner_permalink`** `string | null` - **`permalink`** `string | null` - **`playlist_id`** `string | null` - **`tags`** `array | null` - **`user_id`** `object` **Example:** ```json { "obj": [ { "id": 1, "playlist_id": null, "name": null, "image_url": null, "followers": null, "likes": null, "genre": null, "permalink": null, "owner_name": null, "owner_permalink": null, "user_id": 1, "owner_id": 1, "tags": [ { "id": 0, "name": "", "source": null, "type": null, "url": null, "created_at": null, "modified_at": null } ], "genres": [ { "id": 0, "name": null, "isOverlappingGenre": true } ], "moods": [ { "id": 0, "name": null, "isOverlappingMood": true } ], "isOverlappingGenre": true } ] } ``` ### List Playlist Tracks (Current or Past) - **Method:** `GET` - **Path:** `/api/playlist/{platform}/{id}/{span}/tracks` - **Tags:** Playlist 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. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj` (required)** `array` **Items:** - **`added_at`** `object` - **`album_ids`** `array | null` - **`album_label`** `array | null` - **`album_names`** `array | null` - **`album_upc`** `array | null` - **`artist_covers`** `array | null` - **`artist_images`** `array | null` - **`artist_names`** `array | null` - **`audio_features`** `object | null` - **`acousticness`** `object` - **`danceability`** `object` - **`energy`** `object` - **`instrumentalness`** `object` - **`key`** `integer | null` - **`liveness`** `object` - **`loudness`** `object` - **`mode`** `integer | null` - **`speechiness`** `object` - **`tempo`** `object` - **`valence`** `object` - **`cluster_types`** `array | null` - **`cm_artist`** `array | null` - **`cm_track`** `integer` - **`cm_track_id`** `integer` - **`code2s`** `array | null` - **`id`** `integer` - **`image_url`** `string | null` - **`isrc`** `string | null` - **`name`** `string | null` - **`period`** `integer | null` - **`position`** `integer | null` - **`position_stats`** `array | null` - **`preview_url`** `string | null` - **`release_dates`** `array | null` - **`removed_at`** `object` - **`spotify_album_id`** `string | null` - **`spotify_album_ids`** `array | null` - **`spotify_artist_ids`** `array | null` - **`spotify_artist_names`** `array | null` - **`spotify_duration_ms`** `integer | null` - **`spotify_popularity`** `integer | null` - **`spotify_track_ids`** `array | null` - **`storefront`** `string | null` - **`totaltracks`** `integer | null` - **`track_genre`** `string | null` - **`track_id`** `integer` - **`track_name`** `string | null` **Example:** ```json { "obj": [ { "cm_track_id": 0, "track_id": 0, "isrc": null, "added_at": "", "removed_at": "", "position": null, "period": null, "track_name": null, "name": null, "totaltracks": null, "cluster_types": [ "" ], "id": 0, "spotify_album_id": null, "image_url": null, "spotify_popularity": null, "cm_track": 0, "spotify_artist_names": [ null ], "track_genre": null, "cm_artist": [ 0 ], "artist_names": [ null ], "code2s": [ null ], "artist_images": [ null ], "artist_covers": [ null ], "spotify_artist_ids": [ null ], "spotify_track_ids": [ null ], "spotify_album_ids": [ null ], "spotify_duration_ms": null, "album_ids": [ 0 ], "album_names": [ null ], "album_upc": [ null ], "album_label": [ null ], "release_dates": [ "" ], "audio_features": { "key": null, "mode": null, "danceability": 1, "valence": 1, "energy": 1, "speechiness": 1, "acousticness": 1, "instrumentalness": 1, "liveness": 1, "tempo": 1, "loudness": 1 }, "position_stats": [], "preview_url": null, "storefront": null } ] } ``` ### Get Playlist Evolution by Artist, Album, or Track - **Method:** `GET` - **Path:** `/api/playlist/by/{type}/{id}/evolution` - **Tags:** Playlist Daily playlist-count and total-reach time series across six streaming platforms for the given entity (`artist`, `album`, or `track`). iTunes and Amazon only expose counts (no reach). Reach numbers can exceed the 32-bit range. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj` (required)** `object` **Example:** ```json { "obj": { "spotify": [ { "created_at": "", "playlist_count": null, "ed_playlist_count": null, "playlist_total_reach": null, "ed_playlist_total_reach": null } ], "itunes": [ { "created_at": "", "playlist_count": null, "ed_playlist_count": null } ], "deezer": [ { "created_at": "", "playlist_count": null, "ed_playlist_count": null, "playlist_total_reach": null, "ed_playlist_total_reach": null } ], "amazon": [ { "created_at": "", "playlist_count": null, "ed_playlist_count": null } ], "youtube": [ { "created_at": "", "playlist_count": null, "ed_playlist_count": null, "playlist_total_reach": null, "ed_playlist_total_reach": null } ], "soundcloud": [ { "created_at": "", "playlist_count": null, "ed_playlist_count": null } ] } } ``` ### Get Playlist Journey / Progression - **Method:** `GET` - **Path:** `/api/playlist/{platform}/{id}/journey-progression/{type}` - **Tags:** Playlist Look-back (`journey`) or look-ahead (`progression`) analysis of playlists that share tracks with the target playlist over time. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj`** `object` - **`data` (required)** `array` **Items:** - **`count_distinct_tracks`** `object` - **`events`** `array | null` - **`followers`** `integer | null` - **`image_url`** `string | null` - **`name`** `string | null` - **`plid`** `object` - **`total_percent_overlap`** `number | null`, format: `float` - **`total`** `object` **Example:** ```json { "obj": { "total": 1, "data": [ { "plid": 1, "name": null, "followers": null, "image_url": null, "total_percent_overlap": null, "count_distinct_tracks": 1, "events": [ { "days": null, "day_percent_overlap": null, "tracks_added": [ { "id": 0, "name": null, "image_url": null, "isrc": null } ] } ] } ] } } ``` ### Get Playlist Last Updated Time - **Method:** `GET` - **Path:** `/api/playlist/{platform}/{id}/updated` - **Tags:** Playlist 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. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj`** `object | null` - **`last_added`** `object` - **`last_removed`** `object` - **`playlist_last_updated`** `object` - **`sys_last_updated`** `object` - **`tracks_last_updated`** `object` **Example:** ```json { "obj": { "sys_last_updated": "", "playlist_last_updated": "", "last_added": "", "last_removed": "", "tracks_last_updated": "" } } ``` ### Total Airplays - **Method:** `GET` - **Path:** `/api/radio/{type}/{id}/airplay-totals` - **Tags:** Radio 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. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj` (required)** `object` - **`cities` (required)** `array` **Items:** **Array of:** **Any of:** - **`code2` (required)** `string | null` - **`country` (required)** `string | null` - **`id` (required)** `integer` - **`lat` (required)** `number | null`, format: `float` - **`lng` (required)** `number | null`, format: `float` - **`name` (required)** `string | null` - **`plays` (required)** `object` - **`plays_percent` (required)** `number`, format: `float` - **`station_count`** `integer` - **`top_station_name`** `string | null` **Array of:** - **`air_date` (required)** `object` - **`count` (required)** `object` * Min items: `2` * Max items: `2` - **`countries` (required)** `array` **Items:** **Array of:** **Any of:** - **`code2` (required)** `string` - **`name` (required)** `string | null` - **`plays` (required)** `object` - **`plays_percent` (required)** `number`, format: `float` - **`station_count`** `integer` - **`top_station_name`** `string | null` **Array of:** - **`air_date` (required)** `object` - **`count` (required)** `object` * Min items: `2` * Max items: `2` - **`stations` (required)** `array` **Items:** **Array of:** **Any of:** - **`city` (required)** `string | null` - **`code2` (required)** `string | null` - **`country` (required)** `string | null` - **`id` (required)** `integer` - **`name` (required)** `string | null` - **`plays` (required)** `object` - **`plays_percent` (required)** `number`, format: `float` **Array of:** - **`air_date` (required)** `object` - **`count` (required)** `object` * Min items: `2` * Max items: `2` - **`tracks` (required)** `array` **Items:** **Array of:** **Any of:** - **`id` (required)** `integer` - **`isrc` (required)** `string | null` - **`name` (required)** `string | null` - **`plays` (required)** `object` - **`plays_percent` (required)** `number`, format: `float` - **`station_count`** `integer` - **`top_station_name`** `string | null` **Array of:** - **`air_date` (required)** `object` - **`count` (required)** `object` * Min items: `2` * Max items: `2` **Example:** ```json { "obj": { "countries": [ [ { "code2": "", "name": null, "plays": "", "plays_percent": 1, "station_count": 1, "top_station_name": null } ] ], "cities": [ [ { "id": 0, "name": null, "code2": null, "country": null, "lat": null, "lng": null, "plays": "", "plays_percent": 1, "station_count": 1, "top_station_name": null } ] ], "stations": [ [ { "id": 0, "name": null, "code2": null, "city": null, "country": null, "plays": "", "plays_percent": 1 } ] ], "tracks": [ [ { "id": 0, "name": null, "isrc": null, "plays": "", "plays_percent": 1, "station_count": 1, "top_station_name": null } ] ] } } ``` ### Total Airplays by Entity - **Method:** `GET` - **Path:** `/api/radio/{type}/{id}/airplay-totals/{entity}` - **Tags:** Radio 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. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj` (required)** `array` **Items:** - **`plays` (required)** `object` - **`plays_percent` (required)** `number`, format: `float` - **`plays_trend` (required)** `array` **Items:** - **`air_date` (required)** `object` - **`count` (required)** `object` - **`city`** `string | null` - **`code2`** `string` - **`country`** `string | null` - **`id`** `integer` - **`isrc`** `string | null` - **`lat`** `number | null`, format: `float` - **`lng`** `number | null`, format: `float` - **`name`** `string | null` **Example:** ```json { "obj": [ { "code2": "", "id": 0, "name": null, "country": null, "lat": null, "lng": null, "city": null, "isrc": null, "plays": "", "plays_percent": 1, "plays_trend": [ { "air_date": "", "count": "" } ] } ] } ``` ### Airplay information in Time Series - **Method:** `GET` - **Path:** `/api/radio/{type}/{id}/airplays` - **Tags:** Radio 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. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj` (required)** `array` **Items:** - **`air_date` (required)** `integer` — Unix epoch milliseconds - **`spins` (required)** `integer` **Example:** ```json { "obj": [ { "air_date": 0, "spins": 0 } ] } ``` ### Broadcast Market play counts - **Method:** `GET` - **Path:** `/api/radio/{type}/{id}/broadcast-markets` - **Tags:** Radio 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. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj` (required)** `object` - **`cityRatios` (required)** `array` **Items:** - **`city_id` (required)** `integer` - **`code2` (required)** `string` - **`count` (required)** `number`, format: `float` - **`count_of_stations` (required)** `object` - **`country` (required)** `string | null` - **`display_name` (required)** `string | null` - **`lat` (required)** `number | null`, format: `float` - **`lng` (required)** `number | null`, format: `float` - **`market` (required)** `string | null` - **`market_count_data` (required)** `object` - **`population` (required)** `number | null`, format: `float` - **`total_market_count_data` (required)** `object` - **`countryRatios` (required)** `array` **Items:** - **`code2` (required)** `string` - **`count` (required)** `number`, format: `float` - **`count_of_stations` (required)** `object` - **`lat` (required)** `number | null`, format: `float` - **`lng` (required)** `number | null`, format: `float` - **`market` (required)** `string | null` - **`market_count_data` (required)** `object` - **`population` (required)** `number | null`, format: `float` - **`total_market_count_data` (required)** `object` **Example:** ```json { "obj": { "countryRatios": [ { "market": null, "market_count_data": "", "code2": "", "total_market_count_data": "", "count_of_stations": "", "population": null, "lat": null, "lng": null, "count": 1 } ], "cityRatios": [ { "market": null, "display_name": null, "code2": "", "market_count_data": "", "country": null, "total_market_count_data": "", "count_of_stations": "", "city_id": 0, "population": null, "lat": null, "lng": null, "count": 1 } ] } } ``` ### Get Radio Station List for Country - **Method:** `GET` - **Path:** `/api/radio/station-list` - **Tags:** Radio 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. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj` (required)** `array` **Items:** - **`id` (required)** `integer` - **`name` (required)** `string | null` - **`aqh`** `integer | null` - **`broadcast_area`** `string | null` - **`country`** `string | null` - **`facebook_followers`** `integer | null` - **`facebook_likes`** `integer | null` - **`frequency`** `string | null` - **`genre`** `string | null` - **`image_url`** `string | null` - **`instagram_followers`** `integer | null` - **`market`** `string | null` - **`platform`** `string | null` - **`station_state`** `string | null` - **`twitter_followers`** `integer | null` - **`wikipedia_views`** `integer | null` **Example:** ```json { "obj": [ { "id": 0, "name": null, "genre": null, "frequency": null, "market": null, "broadcast_area": null, "country": null, "station_state": null, "image_url": null, "aqh": null, "platform": null, "facebook_followers": null, "facebook_likes": null, "instagram_followers": null, "twitter_followers": null, "wikipedia_views": null } ] } ``` ### Get TikTok Video Trends for a Track - **Method:** `GET` - **Path:** `/api/track/{id}/video-trends` - **Tags:** Track 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. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj` (required)** `array` **Items:** - **`comments`** `integer | null` - **`likes`** `integer | null` - **`timestp`** `string | null`, format: `date-time` - **`views`** `integer | null` **Example:** ```json { "obj": [ { "timestp": null, "likes": null, "comments": null, "views": null } ] } ``` ### List Chart Appearances for a Track - **Method:** `GET` - **Path:** `/api/track/{id}/{type}/charts` - **Tags:** Track 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. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj`** `object | null` - **`length` (required)** `integer` - **`data`** `array | null` **Example:** ```json { "obj": { "data": [ { "rank": null, "added_at": null, "code2": null, "plays": null, "duration": null, "chart_type": null, "gnp": null, "pre_rank": null, "peak_rank": null, "peak_date": null, "peak_plays": null, "total_plays": null, "id": 1, "cm_track": 1, "name": null, "isrc": null, "image_url": null, "spotify_popularity": null, "spotify_duration_ms": null, "cm_artist": [ 0 ], "artist_names": [ null ], "spotify_artist_ids": [ null ], "spotify_artist_names": [ null ], "spotify_track_ids": [ null ], "spotify_album_ids": [ null ], "itunes_artist_ids": [ null ], "itunes_artist_names": [ null ], "itunes_track_ids": [ null ], "itunes_album_ids": [ null ], "code2s": [ null ], "artist_images": [ null ], "artist_covers": [ null ], "album_ids": [ null ], "album_names": [ null ], "album_upc": [ null ], "album_label": [ null ], "release_dates": [ null ], "storefronts": [ null ], "track_genre": "" } ], "length": 0 } } ``` ### Get Cross-Platform IDs for a Track - **Method:** `GET` - **Path:** `/api/track/{type}/{id}/get-ids` - **Tags:** Track 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. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj`** `array` **Items:** - **`amazon_ids`** `array | null` - **`beatport_ids`** `array | null` - **`chartmetric_ids`** `array | null` - **`deezer_ids`** `array | null` - **`genius_ids`** `array | null` - **`isrc`** `string | null` - **`itunes_ids`** `array | null` - **`qq_ids`** `array | null` - **`shazam_ids`** `array | null` - **`soundcloud_ids`** `array | null` - **`spotify_ids`** `array | null` - **`tiktok_ids`** `array | null` - **`youtube_ids`** `array | null` **Example:** ```json { "obj": [ { "isrc": null, "chartmetric_ids": [ 0 ], "spotify_ids": [ "" ], "itunes_ids": [ "" ], "deezer_ids": [ "" ], "amazon_ids": [ "" ], "youtube_ids": [ "" ], "soundcloud_ids": [ "" ], "shazam_ids": [ "" ], "tiktok_ids": [ "" ], "beatport_ids": [ "" ], "qq_ids": [ "" ], "genius_ids": [ "" ] } ] } ``` ### Get Track Metadata by ID - **Method:** `GET` - **Path:** `/api/track/{id}` - **Tags:** Track 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. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj` (required)** `object` - **`albums` (required)** `array` **Items:** - **`id`** `integer` - **`image_url`** `string | null` - **`label`** `string | null` - **`name`** `string | null` - **`popularity`** `integer | null` - **`release_date`** `string | null`, format: `date-time` - **`upc`** `string | null` - **`artists` (required)** `array` **Items:** - **`id` (required)** `integer` - **`name`** `string | null` - **`id` (required)** `integer` - **`activities`** `array | null` - **`album_label`** `string | null` - **`career_health`** `object` - **`cm_songwriters`** `array | null` - **`cm_statistics`** `object | null` - **`composer_name`** `string | null` - **`duration_ms`** `object` - **`explicit`** `boolean | null` - **`genres`** `array | null` - **`image_url`** `string | null` - **`isrc`** `string | null` - **`moods`** `array | null` - **`name`** `string | null` - **`preview_url`** `string | null` - **`release_date`** `string | null`, format: `date-time` - **`score`** `number | null`, format: `float` - **`songwriters`** `array | null` - **`tags`** `string | null` - **`track_stage`** `object` - **`track_tier`** `integer | null` **Example:** ```json { "obj": { "id": 1, "name": null, "isrc": null, "image_url": null, "preview_url": null, "duration_ms": 1, "composer_name": null, "track_tier": null, "artists": [ { "id": 1, "name": null } ], "albums": [ { "id": 1, "name": null, "upc": null, "release_date": null, "label": null, "image_url": null, "popularity": null } ], "tags": null, "moods": [ { "id": null, "name": null } ], "activities": [ { "id": null, "name": null } ], "genres": [], "songwriters": [ "" ], "cm_songwriters": [], "release_date": null, "album_label": null, "explicit": null, "score": null, "track_stage": null, "career_health": null, "cm_statistics": {} } } ``` ### Get Track Playlist Snapshot by Date - **Method:** `GET` - **Path:** `/api/track/{id}/{platform}/playlists/snapshot` - **Tags:** Track 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. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj`** `array` **Items:** - **`added_at`** `string | null`, format: `date-time` - **`playlist`** `object | null` - **`active_ratio`** `number | null`, format: `float` - **`catalog`** `string | null` - **`code2`** `string | null` - **`description`** `string | null` - **`editorial`** `boolean | null` - **`fdiff_month`** `object` - **`fdiff_week`** `object` - **`followers`** `object` - **`id`** `integer` - **`image_url`** `string | null` - **`last_updated`** `string | null`, format: `date-time` - **`name`** `string | null` - **`num_track`** `object` - **`owner_id`** `integer | null` - **`owner_name`** `string | null` - **`personalized`** `boolean | null` - **`playlist_id`** `string | null` - **`sys_last_updated`** `string | null`, format: `date-time` - **`tags`** `array | null` - **`user_id`** `string | null` - **`playlist_id`** `object` - **`removed_at`** `string | null`, format: `date-time` - **`track`** `object | null` - **`album_ids`** `array | null` - **`album_label`** `array | null` - **`album_names`** `array | null` - **`album_upc`** `array | null` - **`artist_covers`** `array | null` - **`artist_images`** `array | null` - **`artist_names`** `array | null` - **`cm_artist`** `array | null` - **`cm_track`** `integer` - **`code2s`** `array | null` - **`id`** `integer` - **`image_url`** `string | null` - **`isrc`** `string | null` - **`itunes_album_ids`** `array | null` - **`itunes_artist_ids`** `array | null` - **`itunes_artist_names`** `array | null` - **`itunes_track_ids`** `array | null` - **`name`** `string | null` - **`release_dates`** `array | null` - **`spotify_album_ids`** `array | null` - **`spotify_artist_ids`** `array | null` - **`spotify_artist_names`** `array | null` - **`spotify_duration_ms`** `integer | null` - **`spotify_popularity`** `integer | null` - **`spotify_track_ids`** `array | null` - **`storefronts`** `array | null` - **`track_genre`** `object` - **`track_id`** `object` **Example:** ```json { "obj": [ { "playlist_id": 1, "track_id": 1, "added_at": null, "removed_at": null, "playlist": { "id": 1, "name": null, "playlist_id": null, "description": null, "image_url": null, "sys_last_updated": null, "last_updated": null, "personalized": null, "code2": null, "owner_name": null, "owner_id": null, "user_id": null, "editorial": null, "tags": [ { "id": 1, "name": "" } ], "followers": 1, "num_track": 1, "fdiff_week": 1, "fdiff_month": 1, "catalog": null, "active_ratio": null }, "track": { "id": 1, "cm_track": 1, "name": null, "isrc": null, "image_url": null, "spotify_popularity": null, "spotify_duration_ms": null, "cm_artist": [ 0 ], "artist_names": [ null ], "spotify_artist_ids": [ null ], "spotify_artist_names": [ null ], "spotify_track_ids": [ null ], "spotify_album_ids": [ null ], "itunes_artist_ids": [ null ], "itunes_artist_names": [ null ], "itunes_track_ids": [ null ], "itunes_album_ids": [ null ], "code2s": [ null ], "artist_images": [ null ], "artist_covers": [ null ], "album_ids": [ null ], "album_names": [ null ], "album_upc": [ null ], "album_label": [ null ], "release_dates": [ null ], "storefronts": [ null ], "track_genre": "" } } ] } ``` ### Get Track Stats by Platform - **Method:** `GET` - **Path:** `/api/track/{id}/{platform}/stats/{mode}` - **Tags:** Track 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`. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj`** `array` **Items:** - **`domain` (required)** `string` - **`data`** `array | null` - **`track_domain_id`** `string | null` - **`type`** `string | null` **Example:** ```json { "obj": [ { "domain": "", "track_domain_id": null, "type": null, "data": [ { "value": 1, "timestp": null, "daily_diff": null, "interpolated": true } ] } ] } ``` ### List Top YouTube Shorts for a Track - **Method:** `GET` - **Path:** `/api/track/youtube/{id}/topShorts` - **Tags:** Track Return the top YouTube Shorts videos associated with a track. View/like/comment counts may exceed int32. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj`** `object | null` - **`data` (required)** `array` **Items:** - **`cm_id`** `integer | null` - **`comments`** `integer | null` - **`created_at`** `string | null`, format: `date-time` - **`influencercountries`** `array | null` - **`likes`** `integer | null` - **`link`** `string | null` - **`metadata_for_url`** `object | null` - **`modified_at`** `string | null`, format: `date-time` - **`shorts_track_page`** `string | null` - **`sound_id`** `string | null` - **`stats`** `object | null` - **`comments`** `integer | null` - **`likes`** `integer | null` - **`views`** `integer | null` - **`thumbnail_url`** `string | null` - **`token_parameter`** `string | null` - **`username`** `string | null` - **`video_id`** `string | null` - **`video_title`** `string | null` - **`views`** `integer | null` - **`youtubevideohistoricalstats`** `array | null` - **`available_count`** `integer | null` - **`total`** `integer | null` **Example:** ```json { "obj": { "total": null, "available_count": null, "data": [ { "video_id": null, "created_at": null, "modified_at": null, "username": null, "video_title": null, "cm_id": null, "sound_id": null, "token_parameter": null, "thumbnail_url": null, "link": null, "shorts_track_page": null, "views": null, "likes": null, "comments": null, "stats": { "views": null, "likes": null, "comments": null }, "influencercountries": [ "" ], "youtubevideohistoricalstats": [], "metadata_for_url": {} } ] } } ``` ### List Top TikTok Videos for a Track - **Method:** `GET` - **Path:** `/api/track/{id}/topVideos` - **Tags:** Track 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. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj`** `array` **Items:** - **`cm_id`** `object` - **`created_at`** `string | null`, format: `date-time` - **`followers`** `integer | null` - **`link`** `string | null` - **`stats`** `object | null` - **`comments`** `integer | null` - **`likes`** `integer | null` - **`views`** `integer | null` - **`thumbnail_url`** `string | null` - **`username`** `string | null` - **`video_id`** `string | null` **Example:** ```json { "obj": [ { "created_at": null, "username": null, "video_id": null, "thumbnail_url": null, "followers": null, "cm_id": 1, "link": null, "stats": { "likes": null, "comments": null, "views": null } } ] } ``` ### List Related Tracks - **Method:** `GET` - **Path:** `/api/track/{id}/relatedTracks` - **Tags:** Track 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. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj`** `array` **Items:** - **`id` (required)** `integer` - **`is_earliest_cm_track` (required)** `boolean` - **`is_most_popular_cm_track` (required)** `boolean` - **`cluster_type`** `array | null` - **`image_url`** `string | null` - **`isrc`** `string | null` - **`name`** `string | null` **Example:** ```json { "obj": [ { "id": 1, "name": null, "image_url": null, "isrc": null, "is_most_popular_cm_track": true, "is_earliest_cm_track": true, "cluster_type": [ "" ] } ] } ``` ### List Playlists Containing a Track - **Method:** `GET` - **Path:** `/api/track/{id}/{platform}/{status}/playlists` - **Tags:** Track Return playlists that currently (or previously) contain a track. `platform` accepts `spotify`, `applemusic` (aliased to `itunes`), `deezer`, `amazon`. `status` is `current` or `past`. Allowed `sortColumn` values and supported playlist-flag parameters (`editorial`, `personalized`, `chart`, etc.) vary by platform — see the legacy apidoc for the full matrix. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj`** `object` **Example:** ```json { "obj": [ { "playlist": { "id": 1, "name": null, "playlist_id": null, "description": null, "image_url": null, "sys_last_updated": null, "last_updated": null, "personalized": null, "code2": null, "owner_name": null, "owner_id": null, "user_id": null, "editorial": null, "tags": [ { "id": 1, "name": "" } ], "followers": 1, "num_track": 1, "fdiff_week": 1, "fdiff_month": 1, "catalog": null, "active_ratio": null }, "track": { "id": 1, "cm_track": 1, "name": null, "isrc": null, "image_url": null, "spotify_popularity": null, "spotify_duration_ms": null, "cm_artist": [ 0 ], "artist_names": [ null ], "spotify_artist_ids": [ null ], "spotify_artist_names": [ null ], "spotify_track_ids": [ null ], "spotify_album_ids": [ null ], "itunes_artist_ids": [ null ], "itunes_artist_names": [ null ], "itunes_track_ids": [ null ], "itunes_album_ids": [ null ], "code2s": [ null ], "artist_images": [ null ], "artist_covers": [ null ], "album_ids": [ null ], "album_names": [ null ], "album_upc": [ null ], "album_label": [ null ], "release_dates": [ null ], "storefronts": [ null ], "track_genre": "" } } ] } ``` ### List Milestones for a Track - **Method:** `GET` - **Path:** `/api/track/{id}/milestones` - **Tags:** Track 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. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj`** `object` - **`insights` (required)** `array` **Items:** - **`artist_name`** `string | null` - **`date`** `string | null`, format: `date-time` - **`id`** `object` - **`platform`** `string | null` - **`stars`** `integer | null` - **`summary`** `string | null` - **`track_name`** `string | null` - **`count`** `integer | null` **Example:** ```json { "obj": { "insights": [ { "id": 1, "date": null, "summary": null, "artist_name": null, "track_name": null, "platform": null, "stars": null } ], "count": null } } ``` ### List Tracks with Filters - **Method:** `GET` - **Path:** `/api/track/list/filter` - **Tags:** Track Paginated track listing with filter ranges on dozens of platform stats (Spotify plays, TikTok posts, YouTube views, etc.) and sorting on `.` columns. `range_period` selects the stat window (`latest`, `weekly_diff`, `monthly_diff`, `weekly_diff_percent`, `monthly_diff_percent`). Set `originalsOnly=false` to enable `version_*` cluster filters. See the legacy apidoc block for the full stat matrix. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj` (required)** `array` **Items:** - **`offset`** `integer | null` - **`total`** `integer | null` **Example:** ```json { "obj": [ {} ], "offset": null, "total": null } ``` ### List Chartmetric Genres (legacy path) - **Method:** `GET` - **Path:** `/api/genre` - **Tags:** Genre List Chartmetric genres. Accepts `isLegacy` to switch between `genre_v2` (default) and the legacy `genre` taxonomy. Equivalent response shape to `GET /api/genres`. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj` (required)** `array` **Items:** - **`id` (required)** `integer` - **`name` (required)** `string` **Example:** ```json { "obj": [ { "id": 1, "name": "" } ] } ``` ### Festival List - **Method:** `GET` - **Path:** `/api/festival/list` - **Tags:** Festival 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`, or `eventSize`. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj` (required)** `array` **Items:** - **`city` (required)** `string | null` - **`country` (required)** `string | null` - **`date` (required)** `string | null` - **`eventSize` (required)** `string` - **`id` (required)** `integer | null` - **`links` (required)** `object` - **`jambase`** `string | null` - **`seatgeek`** `string | null` - **`songkick`** `string | null` - **`name` (required)** `string | null` - **`numberOfDays` (required)** `integer | null` - **`performersCount` (required)** `integer | null` - **`popularityRank` (required)** `integer | null` - **`topGenres` (required)** `array` **Items:** - **`id` (required)** `integer` - **`name` (required)** `string` **Example:** ```json { "obj": [ { "id": null, "name": null, "date": null, "numberOfDays": null, "city": null, "country": null, "performersCount": null, "popularityRank": null, "eventSize": "", "topGenres": [ { "id": 0, "name": "" } ], "links": { "jambase": null, "songkick": null, "seatgeek": null } } ] } ``` ### List Events for a Venue - **Method:** `GET` - **Path:** `/api/event/venue/{id}` - **Tags:** Event 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 (the ES `hits` array), not a single object. Artist.`is_headliner` reflects the raw boolean from the link table and may be null when the venue has no linked artists. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj`** `object` - **`events` (required)** `array` **Items:** - **`artists` (required)** `array` **Items:** - **`id`** `integer | null` - **`is_headliner`** `boolean | null` - **`name`** `string | null` - **`event_id` (required)** `integer` - **`end_date`** `object` — Currently always an empty string due to a latent reducer bug. - **`event_image_url`** `string | null` - **`event_name`** `string | null` - **`start_date`** `object` - **`venueInfo` (required)** `array` **Items:** - **`capacity`** `integer | null` - **`city_id`** `integer | null` - **`city_name`** `string | null` - **`cm_location`** `integer | null` - **`code2`** `string | null` - **`doc_id`** `object` - **`image_url`** `string | null` - **`lat`** `number | null`, format: `float` - **`lng`** `number | null`, format: `float` - **`name`** `string | null` - **`venue_url`** `string | null` **Example:** ```json { "obj": { "venueInfo": [ { "doc_id": 1, "name": null, "lat": null, "lng": null, "cm_location": null, "code2": null, "image_url": null, "city_id": null, "capacity": null, "city_name": null, "venue_url": null } ], "events": [ { "event_id": 0, "event_name": null, "event_image_url": null, "start_date": "", "end_date": "", "artists": [ { "id": null, "name": null, "is_headliner": null } ] } ] } } ``` ### Get Artist Instagram Top Posts and Reels - **Method:** `GET` - **Path:** `/api/SNS/deepSocial/cm_artist/{id}/instagram` - **Tags:** SNS 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. #### Responses ##### Status: 200 Success ###### Content-Type: application/json - **`obj` (required)** `object` - **`top_posts` (required)** `array` **Items:** - **`created`** `string | null` - **`image`** `string | null` - **`link`** `string | null` - **`mentions`** `array` **Items:** `string` - **`post_id`** `string | null` - **`stat`** `object` - **`comments`** `integer | null` - **`likes`** `integer | null` - **`likes_count_enabled`** `boolean` - **`plays`** `integer | null` - **`shares`** `integer | null` - **`text`** `string | null` - **`thumbnail`** `string | null` - **`type`** `string | null` - **`user_id`** `string | null` - **`user_picture`** `string | null` - **`user_url`** `string | null` - **`username`** `string | null` - **`top_reels` (required)** `array` **Items:** - **`created`** `string | null` - **`image`** `string | null` - **`link`** `string | null` - **`mentions`** `array` **Items:** `string` - **`post_id`** `string | null` - **`stat`** `object` - **`comments`** `integer | null` - **`likes`** `integer | null` - **`likes_count_enabled`** `boolean` - **`plays`** `integer | null` - **`shares`** `integer | null` - **`text`** `string | null` - **`thumbnail`** `string | null` - **`type`** `string | null` - **`user_id`** `string | null` - **`user_picture`** `string | null` - **`user_url`** `string | null` - **`username`** `string | null` **Example:** ```json { "obj": { "top_posts": [ { "user_id": null, "username": null, "user_picture": null, "user_url": null, "type": null, "post_id": null, "created": null, "text": null, "image": null, "thumbnail": null, "link": null, "mentions": [ "" ], "stat": { "likes_count_enabled": true, "likes": null, "comments": null, "shares": null, "plays": null } } ], "top_reels": [ { "user_id": null, "username": null, "user_picture": null, "user_url": null, "type": null, "post_id": null, "created": null, "text": null, "image": null, "thumbnail": null, "link": null, "mentions": [ "" ], "stat": { "likes_count_enabled": true, "likes": null, "comments": null, "shares": null, "plays": null } } ] } } ``` # Quickstart Welcome to the **Chartmetric Developer API**. Programmatic access to artists, tracks, albums, charts, playlists, and brands across streaming, social, and radio platforms. The API is REST-based: predictable resource URLs, JSON responses, standard HTTP status codes. * **Base URL:** `https://api.chartmetric.com` * **Auth:** Bearer access token (short-lived, exchanged from a refresh token) ## 1. Get a Refresh Token Each API user is issued a long-lived refresh token. To sign up, email . The refresh token is sent to your personal email. Treat refresh tokens like passwords. Never commit them or expose them in client-side code. ## 2. Exchange Refresh Token for an Access Token Access tokens expire in **1 hour**. Mint one by `POST`ing your refresh token to `/api/token`: ```bash curl -X POST https://api.chartmetric.com/api/token \ -H "Content-Type: application/json" \ -d '{"refreshtoken":"YOUR_REFRESH_TOKEN"}' ``` bash Response: ```json { "token": "...", "expires_in": 3600, "refresh_token": "...", "scope": "..." } ``` json Reuse the same access token across requests until it expires — do not mint a new one per call. Full details: [Authentication](/guides/authentication). ## 3. Make Your First Request Pass the access token in the `Authorization` header: ```bash curl https://api.chartmetric.com/api/artist/206557 \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" ``` bash Python: ```python from requests import get, post HOST = 'https://api.chartmetric.com' REFRESH_TOKEN = '...' token = post(f'{HOST}/api/token', json={'refreshtoken': REFRESH_TOKEN}).json()['token'] res = get(f'{HOST}/api/artist/206557', headers={'Authorization': f'Bearer {token}'}) print(res.json()) ``` python ## 4. Explore the API * [API Reference](/reference) — every endpoint with parameters, responses, and a try-it console. * [Authentication](/guides/authentication) — token flow, refresh, error handling. * [Rate Limits & Plans](/guides/rate-limits) — throughput tiers and `429` handling. ## Tips * URL-encode strings with non-alphanumeric characters (artist names, track titles). * Array query params use the `param[]=1¶m[]=2` form. * Every response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` headers — use them to pace requests. ## Support Questions or token issues: . API FAQ: [help.chartmetric.com](https://help.chartmetric.com/en/collections/3458598-chartmetric-api). # Authentication The Chartmetric API uses a **two-token** model: | Token | Lifetime | Purpose | | ----------------- | ---------- | ----------------------------------------------------------------------- | | **Refresh token** | Long-lived | Identifies you as an API user. Exchanged for short-lived access tokens. | | **Access token** | 1 hour | Sent on every API request in the `Authorization` header. | ## 1. Obtain a Refresh Token Refresh tokens are issued per API user. To sign up, email . The token is delivered to your personal email. Refresh tokens carry full account privileges: * Never commit them to source control. * Never embed them in client-side / browser code. * Store in a secrets manager or environment variable on the server side only. If you suspect a refresh token is compromised, contact for a rotation. ## 2. Mint an Access Token Exchange the refresh token at `POST https://api.chartmetric.com/api/token`. **Request:** ```bash curl -X POST https://api.chartmetric.com/api/token \ -H "Content-Type: application/json" \ -d '{"refreshtoken":"YOUR_REFRESH_TOKEN"}' ``` bash **Body fields:** | Field | Type | Required | Description | | -------------- | ------ | -------- | ------------------------------- | | `refreshtoken` | string | yes | Your Chartmetric refresh token. | **Response (200):** ```json { "token": "eyJhbGciOi...", "expires_in": 3600, "refresh_token": "...", "scope": "..." } ``` json | Field | Type | Description | | --------------- | ------ | ----------------------------------------------------- | | `token` | string | Access token. Use as `Authorization: Bearer `. | | `expires_in` | number | Seconds until the access token expires. | | `refresh_token` | string | Refresh token to use for the next exchange. | | `scope` | string | Granted access scope. | ## 3. Call the API Send the access token on every request: ```bash curl https://api.chartmetric.com/api/artist/206557 \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" ``` bash **Reuse the same access token until it expires.** Do not call `/api/token` per request — it counts against rate limits and adds latency. ## 4. Handle Expiry Access tokens expire after **1 hour**. When they do, requests return `401 Unauthorized`. Re-mint by calling `/api/token` again with your refresh token. A simple pattern: cache the access token plus an absolute expiry timestamp; refresh when the timestamp is within a small buffer (e.g., 60s) of now. ```python import time from requests import post HOST = 'https://api.chartmetric.com' REFRESH_TOKEN = '...' _token = None _exp = 0 def access_token(): global _token, _exp if _token and time.time() < _exp - 60: return _token res = post(f'{HOST}/api/token', json={'refreshtoken': REFRESH_TOKEN}).json() _token = res['token'] _exp = time.time() + res['expires_in'] return _token ``` python ## 5. Errors | Status | Meaning | Action | | ------ | ----------------------------------- | ----------------------------------------------------------------------------------- | | `400` | Malformed request body. | Verify JSON and the `refreshtoken` field name. | | `401` | Invalid or expired token. | Re-mint an access token. If the refresh token itself is rejected, contact support. | | `403` | Scope does not permit the resource. | Check your plan / scope. | | `429` | Rate limit exceeded. | Back off using `X-RateLimit-Reset`. See [Rate Limits & Plans](/guides/rate-limits). | ## Troubleshooting * **Refresh token rejected:** confirm no leading/trailing whitespace and that the token has not been rotated. Contact . * **Access token works then suddenly fails:** likely 1-hour expiry. Re-mint. * **`Authorization` header ignored:** verify the exact format `Bearer ` (single space, no extra quotes). For per-endpoint auth requirements and try-it requests, see the [API Reference](/reference). # Rate Limits & Plans Chartmetric meters every API plan on a **requests-per-second (req/sec)** basis using a **sliding window** algorithm. Different plans get different limits. Your limit is reported on every response — read the headers and pace accordingly. ## Sliding Window vs Fixed Window The sliding window is **not** broken into fixed clock-aligned periods. It starts from when the **first request** in the window is received and slides forward request-by-request. Example — plan allows 2 req/sec: [![Sliding window rate limit example](https://storage.googleapis.com/cm-app-assets/images/api/sliding-window-rate-limit-example.jpg)]() * A fixed-window view would see two 1-second buckets: 2 requests in the first, 1 in the second — both under the limit. * The sliding window starts at the first request. Within that 1-second slide, **3 requests arrive**, exceeding the 2 req/sec cap. The third request is rate-limited. Takeaway: spacing requests evenly is more reliable than batching them at the start of a clock second. ## Response Headers Every API response carries the current rate-limit state. Use these instead of guessing. | Header | Description | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `X-RateLimit-Limit` | Requests allowed per rate-limit window (usually 1 second). Constant for your plan; only changes when you change subscription. | | `X-RateLimit-Remaining` | Requests left in the current window: `Limit − (requests received in the last window)`. Computed at the moment the request is received — not against fixed clock buckets. | | `X-RateLimit-Reset` | Unix epoch time of the earliest moment a new request would succeed: `(timestamp of oldest request in the last window) + (window duration)`. | When you hit `429 Too Many Requests`, sleep until `X-RateLimit-Reset` before retrying. ```python import time from requests import get res = get(url, headers={'Authorization': f'Bearer {token}'}) if res.status_code == 429: wait = int(res.headers['X-RateLimit-Reset']) - int(time.time()) time.sleep(max(wait, 1)) res = get(url, headers={'Authorization': f'Bearer {token}'}) ``` python ## Throughput The limit counts **requests received**, not requests completed. Endpoints differ in compute cost — some return in <100ms, others take seconds. Throughput in practice depends on both your req/sec ceiling and the latency of the endpoints you call. **Worked example — plan: 25 req/sec, 100 serial requests:** * All 100 requests complete in <1 second each → effective throughput ≈ 25 req/sec, all responses received. * 80 complete in <1s, 20 are computationally heavy and take \~2s → effective throughput ≈ **20 req/sec**. **Tips:** * Parallel requests get responses faster but hit the rate limit sooner. Use a bounded concurrency pool. * A **constant request cadence** maximizes effective throughput. Bursting wastes the window. * For batch jobs, gate concurrency on `X-RateLimit-Remaining` rather than a fixed worker count. ## Plans Each subscription tier has its own req/sec ceiling. To see your current limit, read `X-RateLimit-Limit` from any response. For pricing and to upgrade your plan, contact . ## Handling `429` When a request exceeds your rate limit: * Status: `429 Too Many Requests` * Headers still report `X-RateLimit-Reset` Recommended retry strategy: 1. Read `X-RateLimit-Reset`. 2. Sleep until that timestamp (with a small safety buffer). 3. Retry the request. 4. On repeated `429`s, add exponential backoff and reduce concurrency. Do **not** tight-loop retry — it burns your budget against the same window. ## See Also * [Authentication](/guides/authentication) — token flow and `401` handling. * [API Reference](/reference) — per-endpoint parameters and try-it console. # Connect AI Tools (MCP) Ask your AI assistant questions about Chartmetric endpoints and get answers grounded in these docs — without scrolling the API reference. Works with Claude Code, Claude Desktop, Cursor, Windsurf, and any [MCP](https://modelcontextprotocol.io)-compatible client. > **New here?** The [Quickstart](/) is the fastest way in. Bookmark this page — it's where you'll come when you want to plug Chartmetric into your AI tools. ## What this gives you The MCP server turns these docs into a tool your assistant can call. Without it, you scroll the [API Reference](/reference) looking for the right endpoint. With it, you ask: > _"Which artist endpoint returns Spotify monthly listeners?"_ …and the assistant searches the docs and answers with links. * **Endpoint:** `https://apidocs.chartmetric.com/mcp` (HTTP transport) * **No setup auth.** The docs are public — connect before you even have an API token. * **Different purpose from the API itself.** MCP helps you understand and discover endpoints. Running actual API requests still goes through `api.chartmetric.com` with an access token — see [Authentication](/guides/authentication). ## Install ### Claude Code ```sh claude mcp add --transport http scalar-docs https://apidocs.chartmetric.com/mcp ``` sh `--transport http` is required. Without it, the connection fails. ### Claude Desktop Edit `claude_desktop_config.json` (Settings → Developer → Edit Config): ```json { "mcpServers": { "scalar-docs": { "type": "http", "url": "https://apidocs.chartmetric.com/mcp" } } } ``` json Restart Claude Desktop. ### Cursor Add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per project): ```json { "mcpServers": { "scalar-docs": { "url": "https://apidocs.chartmetric.com/mcp" } } } ``` json ### Other clients Windsurf, Cline, and custom MCP clients: point the client at `https://apidocs.chartmetric.com/mcp` with HTTP transport. ## Use Ask natural-language questions about the API. Examples: * "Which endpoint returns an artist's followers across all DSPs?" * "What query parameters does the playlist tracks endpoint accept?" * "Show the response schema for `/api/artist/:id/tracks`." * "How do I paginate through chart results?" The assistant searches these docs and replies with links back to this site. ## Without MCP: `llms.txt` For tools that don't speak MCP, two static bundles are served at the site root: * [`/llms.txt`](/llms.txt) — index of all pages (small, fits in any context window). * [`/llms-full.txt`](/llms-full.txt) — full content of every page concatenated. Drop either into a system prompt or upload as a file attachment. Both are regenerated weekly from the live OpenAPI spec. ## See also * [Quickstart](/) — first API call in 5 minutes. * [Authentication](/guides/authentication) — token flow your agent will use at runtime. * [Rate Limits & Plans](/guides/rate-limits) — pacing requests in agent loops.