Api documentation

Get playlists

You can sort playlists using specific parameters such as the number of followers, 28-day adds, track count, or last updated date. You can also apply filters based on attributes like genre, type, country, owner, track age, percentage of adds over the last 28 days, or performance metrics.

Please note that you can only retrieve the playlists for one platform at a time.

Here are some useful information:
  • The Get platforms for playlist data endpoint lists available platforms.
  • The documentation for the Get playlist metadata endpoint lists the available countries per platform.
  • These are the available platfom/metricType combinations for the playlist audience:
    • likes: spotify
    • views: youtube
    • fans: deezer
    • followers: jiosaavn
    • favorites: boomplay
  • Review the playlist attributes definition in the help center.

Sort

sort

Name Value Description Additional
Sort object Sort playlists by an attribute or the metric of the selected platform (by total or change over a period) Optional
type string Sort the list of playlists by either:
  • metric: audience metric of the selected platform (only for platforms with an available metric)
  • 28DayAdds: Percentage of songs added to the playlist over 28 days
  • TrackCount: Number of tracks in the playlist
  • LastUpdated: Last updated date of the playlist (this applies to tracks added, removed, or shuffled)

Available values: metric, 28DayAdds, trackCount, lastUpdated		 Required
platform string Use the platfom code selected in the parameters. Only if type is metric
metricType string Type of metric used for sorting playlists.

Find out the available metricType per platform in the description above.		 Only if type is metric
sortBy string Sort the list of playlists by either:
- The latest total value
- Absolute gain/loss over a time period
- Relative gain/loss (in percent) over a time period

Available values: total, volume, percent 		Only if type is metric
period string Time period used in the sorting.

Available values: month, quarter 		Only if type is metric
order string Available values: desc, asc Required

Filters

AttributName Object type Description Additional
type string metric
Filter playlists by any metric
Only for platforms with an available metric. Check the list in the description above. 		Required
data object Required
data.platform string Use the platform code selected in the parameters. Required
data.metricType string Type of metric used for filtering the artists.

Find out the available metricType per platform in the tabs above.		 Required
data.min float Set the minimum value for filtering.

- Enter a number to filter by total value or growth.
- Enter a percentage to filter by percentage growth.		 At least one of min or max is mandatory
data.max float Set the max value for filtering.

- Enter a number to filter by total value or growth.
- Enter a percentage to filter by percentage growth.		 At least one of min or max is mandatory
data.changeType string Choose the type of audience filtering: volume or percent.

- Set "volume" to filter by growth over the time period defined in the period field.
- Set "percent" to filter by percentage growth over the defined time period.
- Leave blank or omit this field to filter by total value.
Optional
data.period string Specify the time period for filtering when changeType is volume or percent.
Available values: month, quarter		 Optional
AttributName Object type Description Additional
type string playlistCountryCode
Filter playlists by their curated country
Countries are available for some platforms. Check the list in the documentation of the Get playlist metadata endpoint. 		Required
data object Required
data.values array of strings A list of 2 letters ISO 3166-2 country codes.

Example: 'US', 'UK'
Full list on https://en.wikipedia.org/wiki/ISO_3166-2		 Required
data.operator string in: Select playlists which country matches any of the specified options.
not_in: Exclude playlists which country matches any of the specified options.		 Required
AttributName Object type Description Additional
type string playlistGenres
Filter playlists by genres 		Required
data object Required
data.values array of strings A list of playlist genres. Please note that sub-genres are not accepted.

Find out the available list Get song genres endpoint.		 Required
data.operator string in: Select playlists which have at least one of the specified genres.
not_in: Exclude playlists which have at least one of the specified genres.		 Required
AttributName Object type Description Additional
type string curators
Filter playlists by curators 		Required
data object Required
data.values array of strings A list of playlist owners.

Find out the available list in the Get curators by platform endpoint		 Required
data.operator string in: Select playlists whose have at least one of the specified owners.
not_in: Exclude playlists whose have at least one of the specified owners.		 Required
AttributName Object type Description Additional
type string type
Filter playlists by type 		Required
data object Required
data.values array of strings A list of playlist types (Algorithmic, Charts, Curators & Listeners, Editorial, Algotorial, Major, Radios, This is...).

All playlist types are listed in this article from our help center. 		Required
data.operator string in: Select playlists whose type matches any of the specified options.
not_in: Exclude playlists whose type matches any of the specified options.		 Required
AttributName Object type Description Additional
type string trackAge
Filter playlists by trackAge 		Required
data object Required
data.values array of strings A list of track age.

Available values: catalog, mixed, frontline 		At least one of the 2 dates is mandatory
data.operator string in: Select playlists whose track age matches any of the specified options.
not_in: Exclude playlists whose track age matches any of the specified options. 		Required
AttributName Object type Description Additional
type string trackCount
Filter playlists by their number of tracks 		Required
data object Required
data.min integer Set the minimum number of tracks At least one of min or max is mandatory
data.max integer Set the maximum number of tracks At least one of min or max is mandatory
AttributName Object type Description Additional
type string 28DayAdds
Filter playlists by the percentage of songs added to the playlist over 28 days 		Required
data object Required
data.min integer Set the minimum number of tracks added At least one of min or max is mandatory
data.max integer Set the maximum number of tracks added At least one of min or max is mandatory

Request

POST /api/v2/top/playlists/{platform}

Path parameters

Parameter name Value Description Additional
platform string

A playlist platform code

 Required

Query string parameters

Parameter name Value Description Additional
offset integer

Get results starting from position
limit integer

Number of results (max. 100)

Body parameters

Parameter name Value Description Additional
body

JSON Payload

 Required

Response

Status code Description Resource
200 OK

Top Playlist collection reponse

 Top Playlist Collection
400 Bad Request

Invalid request
401 Unauthorized

You are not logged in
403 Forbidden

This endpoint is not included in your current plan, reach out to help@soundcharts.com if you want access.

Explore this api

platform

A playlist platform code
offset

Get results starting from position
limit

Number of results (max. 100)
body

JSON Payload
Try it out!