Resolve playlists by UUID or platform identifier and retrieve playlist metadata and current tracklisting across streaming platforms.
openapi: 3.0.1
info:
title: Soundcharts API
description: >-
REST API for the Soundcharts music-market intelligence platform. Provides
standardized metadata and real-time and historical performance data for
artists, songs, albums, and playlists across streaming, social, chart, and
radio sources. Requests are authenticated with the x-app-id and x-api-key
headers.
termsOfService: https://soundcharts.com/en/terms
contact:
name: Soundcharts API Support
url: https://developers.soundcharts.com/api/v2/doc
version: '2.0'
servers:
- url: https://customer.api.soundcharts.com
security:
- AppId: []
ApiKey: []
tags:
- name: Artist
- name: Song
- name: Album
- name: Playlist
- name: Chart
- name: Metrics
- name: Radio
- name: Search
- name: Referential
paths:
/api/v2/artist/{uuid}:
get:
operationId: getArtistMetadata
tags:
- Artist
summary: Get artist metadata
description: >-
Retrieve standardized artist metadata including name, country, genres,
ISNI, IPI, biography, gender, career stage, city, and cross-platform
identifiers.
parameters:
- $ref: '#/components/parameters/Uuid'
responses:
'200':
description: Artist metadata
content:
application/json:
schema:
$ref: '#/components/schemas/ArtistResponse'
'404':
$ref: '#/components/responses/NotFound'
/api/v2/artist/by-platform/{platform}/{identifier}:
get:
operationId: getArtistByPlatformId
tags:
- Artist
summary: Get artist by platform identifier
description: Resolve a Soundcharts artist UUID from a platform identifier.
parameters:
- $ref: '#/components/parameters/Platform'
- $ref: '#/components/parameters/Identifier'
responses:
'200':
description: Artist metadata
content:
application/json:
schema:
$ref: '#/components/schemas/ArtistResponse'
'404':
$ref: '#/components/responses/NotFound'
/api/v2/artist/{uuid}/songs:
get:
operationId: getArtistSongs
tags:
- Artist
summary: Get artist songs
description: List the songs associated with an artist.
parameters:
- $ref: '#/components/parameters/Uuid'
- $ref: '#/components/parameters/Offset'
- $ref: '#/components/parameters/Limit'
responses:
'200':
description: Paginated list of songs
content:
application/json:
schema:
$ref: '#/components/schemas/SongListResponse'
/api/v2/artist/{uuid}/albums:
get:
operationId: getArtistAlbums
tags:
- Artist
summary: Get artist albums
description: List the albums associated with an artist.
parameters:
- $ref: '#/components/parameters/Uuid'
- $ref: '#/components/parameters/Offset'
- $ref: '#/components/parameters/Limit'
responses:
'200':
description: Paginated list of albums
content:
application/json:
schema:
$ref: '#/components/schemas/AlbumListResponse'
/api/v2/artist/{uuid}/related:
get:
operationId: getSimilarArtists
tags:
- Artist
summary: Get similar artists
description: List artists similar to the given artist.
parameters:
- $ref: '#/components/parameters/Uuid'
responses:
'200':
description: Related artists
content:
application/json:
schema:
$ref: '#/components/schemas/ArtistListResponse'
/api/v2/artist/{uuid}/current/stats:
get:
operationId: getArtistCurrentStats
tags:
- Artist
summary: Get artist current stats
description: Retrieve the latest aggregated audience and streaming stats for an artist.
parameters:
- $ref: '#/components/parameters/Uuid'
responses:
'200':
description: Current stats
content:
application/json:
schema:
$ref: '#/components/schemas/StatsResponse'
/api/v2/artist/{uuid}/soundcharts/score:
get:
operationId: getArtistSoundchartsScore
tags:
- Artist
summary: Get Soundcharts score
description: Retrieve the Soundcharts score time series for an artist.
parameters:
- $ref: '#/components/parameters/Uuid'
responses:
'200':
description: Soundcharts score series
content:
application/json:
schema:
$ref: '#/components/schemas/MetricSeriesResponse'
/api/v2/song/{uuid}:
get:
operationId: getSongMetadata
tags:
- Song
summary: Get song metadata
description: Retrieve standardized song metadata by UUID.
parameters:
- $ref: '#/components/parameters/Uuid'
responses:
'200':
description: Song metadata
content:
application/json:
schema:
$ref: '#/components/schemas/SongResponse'
'404':
$ref: '#/components/responses/NotFound'
/api/v2/song/by-isrc/{isrc}:
get:
operationId: getSongByIsrc
tags:
- Song
summary: Get song by ISRC
description: Resolve a song by its ISRC code.
parameters:
- name: isrc
in: path
required: true
description: International Standard Recording Code.
schema:
type: string
responses:
'200':
description: Song metadata
content:
application/json:
schema:
$ref: '#/components/schemas/SongResponse'
'404':
$ref: '#/components/responses/NotFound'
/api/v2/song/by-platform/{platform}/{identifier}:
get:
operationId: getSongByPlatformId
tags:
- Song
summary: Get song by platform identifier
description: Resolve a song by a platform identifier.
parameters:
- $ref: '#/components/parameters/Platform'
- $ref: '#/components/parameters/Identifier'
responses:
'200':
description: Song metadata
content:
application/json:
schema:
$ref: '#/components/schemas/SongResponse'
/api/v2/song/{uuid}/audio-features:
get:
operationId: getSongAudioFeatures
tags:
- Song
summary: Get song audio features
description: Retrieve audio features (tempo, energy, danceability, etc.) for a song.
parameters:
- $ref: '#/components/parameters/Uuid'
responses:
'200':
description: Audio features
content:
application/json:
schema:
$ref: '#/components/schemas/GenericObjectResponse'
/api/v2/song/{uuid}/audience/{platform}:
get:
operationId: getSongAudience
tags:
- Metrics
summary: Get song audience
description: Retrieve the audience metric time series for a song on a platform.
parameters:
- $ref: '#/components/parameters/Uuid'
- $ref: '#/components/parameters/Platform'
- $ref: '#/components/parameters/StartDate'
- $ref: '#/components/parameters/EndDate'
responses:
'200':
description: Audience series
content:
application/json:
schema:
$ref: '#/components/schemas/MetricSeriesResponse'
/api/v2/album/by-uuid/{uuid}:
get:
operationId: getAlbumMetadata
tags:
- Album
summary: Get album metadata
description: Retrieve standardized album metadata by UUID.
parameters:
- $ref: '#/components/parameters/Uuid'
responses:
'200':
description: Album metadata
content:
application/json:
schema:
$ref: '#/components/schemas/AlbumResponse'
'404':
$ref: '#/components/responses/NotFound'
/api/v2/album/by-upc/{upc}:
get:
operationId: getAlbumByUpc
tags:
- Album
summary: Get album by UPC
description: Resolve an album by its UPC code.
parameters:
- name: upc
in: path
required: true
description: Universal Product Code.
schema:
type: string
responses:
'200':
description: Album metadata
content:
application/json:
schema:
$ref: '#/components/schemas/AlbumResponse'
'404':
$ref: '#/components/responses/NotFound'
/api/v2/album/by-platform/{platform}/{identifier}:
get:
operationId: getAlbumByPlatformId
tags:
- Album
summary: Get album by platform identifier
description: Resolve an album by a platform identifier.
parameters:
- $ref: '#/components/parameters/Platform'
- $ref: '#/components/parameters/Identifier'
responses:
'200':
description: Album metadata
content:
application/json:
schema:
$ref: '#/components/schemas/AlbumResponse'
/api/v2.26/album/{uuid}/tracks:
get:
operationId: getAlbumTracks
tags:
- Album
summary: Get album tracklisting
description: List the tracks contained in an album.
parameters:
- $ref: '#/components/parameters/Uuid'
- $ref: '#/components/parameters/Offset'
- $ref: '#/components/parameters/Limit'
responses:
'200':
description: Album tracklisting
content:
application/json:
schema:
$ref: '#/components/schemas/SongListResponse'
/api/v2/playlist/{uuid}:
get:
operationId: getPlaylistMetadata
tags:
- Playlist
summary: Get playlist metadata
description: Retrieve standardized playlist metadata by UUID.
parameters:
- $ref: '#/components/parameters/Uuid'
responses:
'200':
description: Playlist metadata
content:
application/json:
schema:
$ref: '#/components/schemas/PlaylistResponse'
'404':
$ref: '#/components/responses/NotFound'
/api/v2/playlist/by-platform/{platform}/{identifier}:
get:
operationId: getPlaylistByPlatformId
tags:
- Playlist
summary: Get playlist by platform identifier
description: Resolve a playlist by a platform identifier.
parameters:
- $ref: '#/components/parameters/Platform'
- $ref: '#/components/parameters/Identifier'
responses:
'200':
description: Playlist metadata
content:
application/json:
schema:
$ref: '#/components/schemas/PlaylistResponse'
/api/v2/playlist/{uuid}/tracks:
get:
operationId: getPlaylistTracks
tags:
- Playlist
summary: Get playlist tracklisting
description: Retrieve the current tracklisting for a playlist.
parameters:
- $ref: '#/components/parameters/Uuid'
- $ref: '#/components/parameters/Offset'
- $ref: '#/components/parameters/Limit'
responses:
'200':
description: Playlist tracklisting
content:
application/json:
schema:
$ref: '#/components/schemas/SongListResponse'
/api/v2/chart/song/by-platform/{platform}:
get:
operationId: getSongChartsByPlatform
tags:
- Chart
summary: Get song charts by platform
description: List the available song charts for a platform.
parameters:
- $ref: '#/components/parameters/Platform'
responses:
'200':
description: List of charts
content:
application/json:
schema:
$ref: '#/components/schemas/ChartListResponse'
/api/v2/chart/song/{slug}/ranking/latest:
get:
operationId: getSongRankingLatest
tags:
- Chart
summary: Get latest song ranking
description: Retrieve the latest ranking for a song chart.
parameters:
- $ref: '#/components/parameters/Slug'
- $ref: '#/components/parameters/Offset'
- $ref: '#/components/parameters/Limit'
responses:
'200':
description: Chart ranking
content:
application/json:
schema:
$ref: '#/components/schemas/RankingResponse'
/api/v2/chart/song/{slug}/ranking/{datetime}:
get:
operationId: getSongRankingForDate
tags:
- Chart
summary: Get song ranking for a date
description: Retrieve a song chart ranking for a specific date.
parameters:
- $ref: '#/components/parameters/Slug'
- name: datetime
in: path
required: true
description: Ranking date in ISO 8601 format.
schema:
type: string
format: date-time
responses:
'200':
description: Chart ranking
content:
application/json:
schema:
$ref: '#/components/schemas/RankingResponse'
/api/v2/chart/album/{slug}/ranking/latest:
get:
operationId: getAlbumRankingLatest
tags:
- Chart
summary: Get latest album ranking
description: Retrieve the latest ranking for an album chart.
parameters:
- $ref: '#/components/parameters/Slug'
- $ref: '#/components/parameters/Offset'
- $ref: '#/components/parameters/Limit'
responses:
'200':
description: Chart ranking
content:
application/json:
schema:
$ref: '#/components/schemas/RankingResponse'
/api/v2/chart/tiktok/music/weekly/ranking/latest:
get:
operationId: getTiktokMusicRankingLatest
tags:
- Chart
summary: Get latest TikTok weekly music ranking
description: Retrieve the latest TikTok weekly music ranking.
responses:
'200':
description: Chart ranking
content:
application/json:
schema:
$ref: '#/components/schemas/RankingResponse'
/api/v2/artist/{uuid}/audience/{platform}:
get:
operationId: getArtistAudience
tags:
- Metrics
summary: Get artist audience
description: Retrieve the follower/audience time series for an artist on a platform.
parameters:
- $ref: '#/components/parameters/Uuid'
- $ref: '#/components/parameters/Platform'
- $ref: '#/components/parameters/StartDate'
- $ref: '#/components/parameters/EndDate'
responses:
'200':
description: Audience series
content:
application/json:
schema:
$ref: '#/components/schemas/MetricSeriesResponse'
/api/v2/artist/{uuid}/streaming/{platform}/listening:
get:
operationId: getArtistStreamingAudience
tags:
- Metrics
summary: Get artist streaming audience
description: Retrieve the streaming listening audience time series for an artist on a platform.
parameters:
- $ref: '#/components/parameters/Uuid'
- $ref: '#/components/parameters/Platform'
- $ref: '#/components/parameters/StartDate'
- $ref: '#/components/parameters/EndDate'
responses:
'200':
description: Streaming audience series
content:
application/json:
schema:
$ref: '#/components/schemas/MetricSeriesResponse'
/api/v2/artist/{uuid}/popularity/{platform}:
get:
operationId: getArtistPopularity
tags:
- Metrics
summary: Get artist popularity
description: Retrieve the popularity index time series for an artist on a platform.
parameters:
- $ref: '#/components/parameters/Uuid'
- $ref: '#/components/parameters/Platform'
responses:
'200':
description: Popularity series
content:
application/json:
schema:
$ref: '#/components/schemas/MetricSeriesResponse'
/api/v2/radio/{uuid}:
get:
operationId: getRadio
tags:
- Radio
summary: Get radio station
description: Retrieve radio station metadata by UUID.
parameters:
- $ref: '#/components/parameters/Uuid'
responses:
'200':
description: Radio station metadata
content:
application/json:
schema:
$ref: '#/components/schemas/GenericObjectResponse'
'404':
$ref: '#/components/responses/NotFound'
/api/v2/radio/by-slug/{slug}:
get:
operationId: getRadioBySlug
tags:
- Radio
summary: Get radio station by slug
description: Resolve a radio station by slug.
parameters:
- $ref: '#/components/parameters/Slug'
responses:
'200':
description: Radio station metadata
content:
application/json:
schema:
$ref: '#/components/schemas/GenericObjectResponse'
/api/v2/artist/{uuid}/broadcasts:
get:
operationId: getArtistRadioSpins
tags:
- Radio
summary: Get artist radio spins
description: List radio airplay spins (broadcasts) for an artist.
parameters:
- $ref: '#/components/parameters/Uuid'
- $ref: '#/components/parameters/Offset'
- $ref: '#/components/parameters/Limit'
responses:
'200':
description: Radio spins
content:
application/json:
schema:
$ref: '#/components/schemas/GenericListResponse'
/api/v2/search:
post:
operationId: search
tags:
- Search
summary: Search the catalog
description: Search for artists, songs, albums, playlists, venues, and festivals by name.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SearchRequest'
responses:
'200':
description: Search results
content:
application/json:
schema:
$ref: '#/components/schemas/GenericListResponse'
/api/v2/referential/platforms:
get:
operationId: getPlatforms
tags:
- Referential
summary: Get platforms
description: List the platforms supported by the Soundcharts API.
responses:
'200':
description: List of platforms
content:
application/json:
schema:
$ref: '#/components/schemas/GenericListResponse'
components:
securitySchemes:
AppId:
type: apiKey
in: header
name: x-app-id
description: Soundcharts application identifier.
ApiKey:
type: apiKey
in: header
name: x-api-key
description: Soundcharts API key.
parameters:
Uuid:
name: uuid
in: path
required: true
description: Soundcharts entity UUID.
schema:
type: string
format: uuid
Platform:
name: platform
in: path
required: true
description: Platform slug (e.g. spotify, apple-music, youtube, instagram, tiktok).
schema:
type: string
Identifier:
name: identifier
in: path
required: true
description: Platform-specific identifier for the entity.
schema:
type: string
Slug:
name: slug
in: path
required: true
description: Chart, radio, or entity slug.
schema:
type: string
Offset:
name: offset
in: query
required: false
description: Pagination offset.
schema:
type: integer
default: 0
Limit:
name: limit
in: query
required: false
description: Maximum number of items to return.
schema:
type: integer
default: 100
StartDate:
name: startDate
in: query
required: false
description: Start of the date range (ISO 8601).
schema:
type: string
format: date
EndDate:
name: endDate
in: query
required: false
description: End of the date range (ISO 8601).
schema:
type: string
format: date
responses:
NotFound:
description: Entity not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
schemas:
Related:
type: object
properties:
self:
type: string
previous:
type: string
nullable: true
next:
type: string
nullable: true
Page:
type: object
properties:
offset:
type: integer
limit:
type: integer
total:
type: integer
Artist:
type: object
properties:
uuid:
type: string
format: uuid
slug:
type: string
name:
type: string
appUrl:
type: string
imageUrl:
type: string
nullable: true
countryCode:
type: string
nullable: true
gender:
type: string
nullable: true
type:
type: string
nullable: true
biography:
type: string
nullable: true
isni:
type: string
nullable: true
ipi:
type: string
nullable: true
genres:
type: array
items:
type: object
properties:
root:
type: string
sub:
type: array
items:
type: string
Song:
type: object
properties:
uuid:
type: string
format: uuid
name:
type: string
isrc:
type: object
nullable: true
properties:
value:
type: string
countryCode:
type: string
creditName:
type: string
nullable: true
releaseDate:
type: string
format: date-time
nullable: true
duration:
type: integer
nullable: true
artists:
type: array
items:
$ref: '#/components/schemas/Artist'
Album:
type: object
properties:
uuid:
type: string
format: uuid
name:
type: string
type:
type: string
nullable: true
upc:
type: string
nullable: true
releaseDate:
type: string
format: date-time
nullable: true
label:
type: string
nullable: true
artists:
type: array
items:
$ref: '#/components/schemas/Artist'
Playlist:
type: object
properties:
uuid:
type: string
format: uuid
name:
type: string
platform:
type: string
type:
type: string
nullable: true
curator:
type: string
nullable: true
latestSubscriberCount:
type: integer
nullable: true
latestTrackCount:
type: integer
nullable: true
Chart:
type: object
properties:
slug:
type: string
name:
type: string
platform:
type: string
type:
type: string
countryCode:
type: string
nullable: true
frequency:
type: string
nullable: true
RankingEntry:
type: object
properties:
position:
type: integer
oldPosition:
type: integer
nullable: true
timeOnChart:
type: integer
nullable: true
song:
$ref: '#/components/schemas/Song'
MetricPoint:
type: object
properties:
date:
type: string
format: date-time
value:
type: number
platform:
type: string
nullable: true
ArtistResponse:
type: object
properties:
object:
$ref: '#/components/schemas/Artist'
SongResponse:
type: object
properties:
object:
$ref: '#/components/schemas/Song'
AlbumResponse:
type: object
properties:
object:
$ref: '#/components/schemas/Album'
PlaylistResponse:
type: object
properties:
object:
$ref: '#/components/schemas/Playlist'
StatsResponse:
type: object
properties:
object:
type: object
additionalProperties: true
GenericObjectResponse:
type: object
properties:
object:
type: object
additionalProperties: true
ArtistListResponse:
type: object
properties:
page:
$ref: '#/components/schemas/Page'
related:
$ref: '#/components/schemas/Related'
items:
type: array
items:
$ref: '#/components/schemas/Artist'
SongListResponse:
type: object
properties:
page:
$ref: '#/components/schemas/Page'
related:
$ref: '#/components/schemas/Related'
items:
type: array
items:
$ref: '#/components/schemas/Song'
AlbumListResponse:
type: object
properties:
page:
$ref: '#/components/schemas/Page'
related:
$ref: '#/components/schemas/Related'
items:
type: array
items:
$ref: '#/components/schemas/Album'
ChartListResponse:
type: object
properties:
page:
$ref: '#/components/schemas/Page'
related:
$ref: '#/components/schemas/Related'
items:
type: array
items:
$ref: '#/components/schemas/Chart'
RankingResponse:
type: object
properties:
page:
$ref: '#/components/schemas/Page'
related:
$ref: '#/components/schemas/Related'
items:
type: array
items:
$ref: '#/components/schemas/RankingEntry'
MetricSeriesResponse:
type: object
properties:
related:
$ref: '#/components/schemas/Related'
items:
type: array
items:
$ref: '#/components/schemas/MetricPoint'
GenericListResponse:
type: object
properties:
page:
$ref: '#/components/schemas/Page'
related:
$ref: '#/components/schemas/Related'
items:
type: array
items:
type: object
additionalProperties: true
SearchRequest:
type: object
properties:
type:
type: string
description: Entity type to search (artist, song, album, playlist).
term:
type: string
description: Search term.
required:
- type
- term
ErrorResponse:
type: object
properties:
errors:
type: array
items:
type: object
properties:
key:
type: string
code:
type: integer
message:
type: string