--- title: "Chartmetric Search" method: GET path: "/api/search" tags: ["Search"] --- # Chartmetric Search `GET /api/search` ## Request - Base URL: `https://api.chartmetric.com` - URL: `https://api.chartmetric.com/api/search` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) 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. ## Query parameters - `q` string, required: Search query. Free text matched across artists, tracks, albums, playlists, curators, stations, cities, and songwriters; or a streaming/social URL to look up a single entity by its native ID. - `limit` integer: Maximum number of items to return per request. - `offset` integer: Number of items to skip from the start of the result set; pair with `limit` to paginate. - `type` 'all' | 'artists' | 'tracks' | 'playlists' | 'curators' | 'albums' | 'stations' | 'cities' | 'songwriters': Restrict the search to a single entity bucket. One of `all`, `artists`, `tracks`, `playlists`, `curators`, `albums`, `stations`, `cities`, `songwriters`. Defaults to `all`. - `beta` boolean: If true, use the beta global-search engine which returns a flat `suggestions` list with `match_strength` and `target` per item instead of bucketed results. - `platforms` string[]: Restrict beta search to these platforms. Only valid when `beta=true`. One or more of `cm`, `spotify`, `itunes`, `applemusic`, `deezer`, `amazon`, `youtube`, `tidal`, `soundcloud`, `acr`. - `triggerCitiesOnly` boolean: If true, restrict city results to Chartmetric Trigger Cities. Available for both beta and non-beta search. ## Response `200` Success - object - `obj` object, required - `artists` object[], required: Artist matches. - `id` integer, required: Chartmetric artist ID. - `name` string, required: Artist name. - `image_url` string, nullable: Artist image URL. - `isni` string, nullable: International Standard Name Identifier (ISNI) of the artist. - `sp_followers` integer, nullable: Spotify follower count. - `sp_monthly_listeners` integer, nullable: Spotify monthly listener count. - `cm_artist_score` number, float, nullable: Chartmetric artist score (composite popularity metric). - `playlists` object, required: Playlist matches grouped by streaming platform. - `spotify` object[], required: Spotify playlist matches. - `id` integer, required: Chartmetric playlist ID. - `name` string, required: Playlist name. - `image_url` string, nullable: Playlist cover image URL. - `owner_name` string, nullable: Playlist owner / curator's display name. - `applemusic` object[], required: Apple Music playlist matches. - `id` integer, required: Chartmetric playlist ID. - `name` string, required: Playlist name. - `image_url` string, nullable: Playlist cover image URL. - `owner_name` string, nullable: Playlist owner / curator's display name. - `deezer` object[], required: Deezer playlist matches. - `id` union, required: Chartmetric playlist ID. May be returned as a string for platform-native IDs. - string - integer - `name` string, required: Playlist name. - `image_url` string, nullable: Playlist cover image URL. - `owner_name` string, nullable: Playlist owner / curator's display name. - `amazon` object[], required: Amazon Music playlist matches. - `id` union, required: Chartmetric playlist ID. May be returned as a string for platform-native IDs. - string - integer - `name` string, required: Playlist name. - `image_url` string, nullable: Playlist cover image URL. - `owner_name` string, nullable: Playlist owner / curator's display name. - `youtube` object[], required: YouTube playlist matches. - `id` string, required: YouTube playlist ID. - `name` string, required: Playlist name. - `image_url` string, nullable: Playlist cover image URL. - `soundcloud` unknown[], required: SoundCloud playlist matches. - unknown - `tracks` object[], required: Track matches. - `id` union, required: Chartmetric track ID. May be returned as a string or number. - string - number, float - `name` string, required: Track name. - `image_url` string, nullable: Track cover image URL. - `isrc` string, nullable: International Standard Recording Code identifying the track. - `artist_names` string[], required: Artist names credited on the track. - `curators` object, required: Curator matches grouped by streaming platform. - `spotify` object[], required: Spotify curator matches. - `id` integer, required: Chartmetric curator ID. - `name` string, nullable: Curator's display name. - `image_url` string, nullable: Curator profile image URL. - `applemusic` object[], required: Apple Music curator matches. - `id` integer, required: Chartmetric curator ID. - `name` string, nullable: Curator's display name. - `image_url` string, nullable: Curator profile image URL. - `deezer` object[], required: Deezer curator matches. - `id` union, required: Chartmetric curator ID. May be returned as a string for platform-native IDs. - string - integer - `name` string, nullable: Curator's display name. - `image_url` string, nullable: Curator profile image URL. - `amazon` unknown[], required: Amazon Music curator matches. - unknown - `youtube` unknown[], required: YouTube curator matches. - unknown - `albums` object[], required: Album matches. - `id` integer, required: Chartmetric album ID. - `name` string, required: Album name. - `image_url` string, nullable: Album cover image URL. - `label` string, nullable: Record label that released the album. - `stations` object[], required: Radio and SiriusXM station matches. - `id` integer, required: Chartmetric station ID. - `name` string, required: Radio/SiriusXM station name. - `genre` string, nullable: Genre format of the station. - `image_url` string, nullable: Station logo or image URL. - `station_city` string, nullable: City where the station is broadcast from. - `country` string, nullable: Country where the station is broadcast from. - `labels` unknown[], required: Record label matches. - unknown - `cities` object[], required: City matches. - `id` integer, required: Chartmetric city ID. - `name` string, required: City name. - `name_ascii` string, nullable: ASCII-only transliteration of the city name. - `population` number, float, nullable: City population. Used to disambiguate same-named cities across other endpoints. - `country` string, nullable: Country name. - `code2` string, nullable: ISO 3166-1 alpha-2 country code (2 letters, e.g. 'US', 'BR', 'GB'). - `province` string, nullable: State, province, or first-level administrative subdivision. - `trigger_city` boolean: Whether the city is classified as a Chartmetric Trigger City. - `countries` unknown[]: Country matches. - unknown - `songwriters` object[], required: Songwriter matches. - `name` string, nullable: Songwriter name. - `doc_id` integer, required: Chartmetric songwriter ID. - `artistName` string, nullable: Linked artist name when the songwriter also performs. - `image_url` string, nullable: Songwriter image URL. - `genres` unknown[], required: Genre matches. - unknown - `festivals` unknown[], required: Festival matches. - unknown --- [API](https://skmtc.dev/chartmetric/apis/chartmetric-developer-api.md) - [All operations](https://skmtc.dev/chartmetric/apis/chartmetric-developer-api/llms.txt) - [OpenAPI document](https://skmtc.dev/chartmetric/apis/chartmetric-developer-api/revisions/94dac96833a3?raw)