Get songs
This endpoint is restricted to specific plans. Reach out if you have any questions.
Distributor data is currently in Beta and may contain inaccuracies. If you notice any error, please contact us.
Get a list of songs filtered by attributes and stats.
You can sort songs in our database using specific parameters such as platform, metric type, or time period, and filter them based on attributes like artist nationality, ISRC country, song genre, release date, attributes from lyrics analysis, etc. or performance metrics.
Here are the available platfom/metricType combinations, sorted by type:
Consumption metrics
- plays: anghami, audiomack, jiosaavn, soundcloud
- streams: spotify, line-music
- count: shazam
- views: youtube
Radio metrics
- plays: airplay
Popularity
- popularity: spotify
Audience metrics
- favorites: boomplay, gaana
- likes: melon
Other
- videos: tiktok
Sort
| Name | Value | Description | Additional |
|---|---|---|---|
| Sort | object | Sort songs by a metric (by total or change over a period) | Optional |
| platform | string | Code of the platform used for the sorting metric. Available values are listed in the Get platforms endpoint |
|
| metricType | string | Type of metric used for sorting the songs. Find out the available metricType per platform in the description above. |
|
| sortBy | string | Sort the list of songs 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 | |
| period | string | Time period used in the sorting. Available values: week, month, quarter |
|
| order | string | Available values: desc, asc |
Filters
| AttributName | Object type | Description | Additional |
|---|---|---|---|
| type | string | metric Filter songs by any metric |
Required |
| data | object | Required | |
| data.platform | string | Code of the platform used for the filtering metric. Available values are listed in the Get platforms endpoint |
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.period | string | Specify the time period for filtering when changeType is volume or percent. Available values: week, month, quarter |
Optional |
| 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 |
| AttributName | Object type | Description | Additional |
|---|---|---|---|
| type | string | artistCountryCodes Filter songs by the nationality of their artists |
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 songs where at least one artist's nationality matches any of the specified options. not_in: Exclude songs where at least one artist's nationality matches any of the specified options. |
Required |
| AttributName | Object type | Description | Additional |
|---|---|---|---|
| type | string | songGenres Filter songs by genres |
Required |
| data | object | Required | |
| data.values | array of strings | A list of song genres. Find out the available list Get song genres endpoint. |
Required |
| data.operator | string | in: Select songs who have at least one of the specified genres. not_in: Exclude songs who have at least one of the specified genres. |
Required |
| AttributName | Object type | Description | Additional |
|---|---|---|---|
| type | string | songSubGenres Filter songs by sub genres |
Required |
| data | object | Required | |
| data.values | array of strings | A list of song sub genres. Find out the available list Get song genres endpoint. |
Required |
| data.operator | string | in: Select songs who have at least one of the specified sub genres. not_in: Exclude songs who have at least one of the specified sub genres. |
Required |
| AttributName | Object type | Description | Additional |
|---|---|---|---|
| type | string | isrcCountryCode Filters songs based on the country of production (root of the ISRC). |
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 songs whose ISRC country code matches any of the specified options. not_in: Exclude songs whose ISRC country code matches any of the specified options. |
Required |
| AttributName | Object type | Description | Additional |
|---|---|---|---|
| type | string | releaseDate Filter songs based on the date of their release. |
Required |
| data | object | Required | |
| data.min | YYYY-MM-DD | Select songs whose first release occurred later than the specified date. | At least one of the 2 dates is mandatory |
| data.max | YYYY-MM-DD | Select songs whose first release occurred earlier than the specified date. | At least one of the 2 dates is mandatory |
| data.operator | string | in: Select songs whose release matches the specified range. not_in: Exclude songs whose release matches the specified range. |
Required |
| AttributName | Object type | Description | Additional |
|---|---|---|---|
| type | string | labelTypes Filter songs by the types of the labels they were released under. |
Required |
| data | object | Required | |
| data.values | array of strings | A list of label types. Find out the available list in the Get label types endpoint |
Required |
| data.operator | string | in: Select songs where at least one of their labels' type matches any of the specified options. not_in: Exclude songs where at least one of their labels' type matches any of the specified options. | Required |
| AttributName | Object type | Description | Additional |
|---|---|---|---|
| type | string | distributor Filter songs by their distributor. |
Required |
| data.values | array of strings | A list of distributors. Find out the available list in the Get distributors endpoint |
Required |
| data.operator | string | in: Select songs where at least one of their distributor matches any of the specified options. not_in: Exclude songs where at least one of their distributor matches any of the specified options. | Required |
| AttributName | Object type | Description | Additional |
|---|---|---|---|
| type | string | explicit Filter songs with or without explicit language. |
Required |
| data | object | Required | |
| data.value | boolean | Available values: true, false | Required |
| AttributName | Object type | Description | Additional |
|---|---|---|---|
| type | string | themes Filter songs by themes identified in the lyrics. |
Required |
| data | object | Required | |
| data.values | array of strings | A list of themes Find out the available list in the Get lyrics attributes endpoint. |
At least one of the 2 dates is mandatory |
| data.operator | string | in: Select songs who have at least one of the specified themes. not_in: Exclude songs who have at least one of the specified themes. | Required |
| AttributName | Object type | Description | Additional |
|---|---|---|---|
| type | string | moods Filter songs by moods identified in the lyrics. |
Required |
| data | object | Required | |
| data.values | array of strings | A list of moods Find out the available list in the Get lyrics attributes endpoint. |
Required |
| data.operator | string | in: Select songs who have at least one of the specified moods. not_in: Exclude songs who have at least one of the specified moods. | Required |
| AttributName | Object type | Description | Additional |
|---|---|---|---|
| type | string | culturalReferencePeople Filter songs by people mentionned in the lyrics |
Required |
| data | object | Required | |
| data.values | array of strings | A list of people Find out the available list in the Get lyrics attributes endpoint. |
Required |
| data.operator | string | in: Select songs who have at least one of the specified people. not_in: Exclude songs who have at least one of the specified people. | Required |
| AttributName | Object type | Description | Additional |
|---|---|---|---|
| type | string | culturalReferenceNonPeople Filter songs by cultural references mentionned in the lyrics |
Required |
| data | object | Required | |
| data.values | array of strings | A list of cultural references. Find out the available list in the Get lyrics attributes endpoint. |
Required |
| data.operator | string | in: Select songs who have at least one of the specified reference. not_in: Exclude songs who have at least one of the specified reference. | Required |
| AttributName | Object type | Description | Additional |
|---|---|---|---|
| type | string | brands Filter songs by brands mentionned in the lyrics |
Required |
| data | object | Required | |
| data.values | array of strings | A list of brands Find out the available list in the Get lyrics attributes endpoint. |
Required |
| data.operator | string | in: Select songs who have at least one of the specified brands. not_in: Exclude songs who have at least one of the specified brands. | Required |
| AttributName | Object type | Description | Additional |
|---|---|---|---|
| type | string | locations Filter songs by location mentionned in the lyrics |
Required |
| data | object | Required | |
| data.values | array of strings | A list of locations Find out the available list in the Get lyrics attributes endpoint. |
Required |
| data.operator | string | in: Select songs who have at least one of the specified locations. not_in: Exclude songs who have at least one of the specified locations. | Required |
| AttributName | Object type | Description | Additional |
|---|---|---|---|
| type | string | narrativeStyle Filter songs by narrative style identified in the lyrics. |
Required |
| data | object | Required | |
| data.values | array of integer | A list of score Available values: from 1 to 4. 1 = 1st person, 2 = 2nd person, 3 = 3rd person, 4 = character voices. |
Required |
| data.operator | string | in: Select songs whose score is in the list. not_in: Exclude songs whose score is in the list. | Required |
| AttributName | Object type | Description | Additional |
|---|---|---|---|
| type | string | emotionalIntensityScore Filter songs by emotional intensity score identified in the lyrics. |
Required |
| data | object | Required | |
| data.values | array of integer | A list of score Available values: from 1 to 10. 1: Lowest, 10: Highest. |
Required |
| data.operator | string | in: Select songs whose score is in the list. not_in: Exclude songs whose score is in the list. | Required |
| AttributName | Object type | Description | Additional |
|---|---|---|---|
| type | string | imageryScore Filter songs by imagery score identified in the lyrics. | Required |
| data | object | Required | |
| data.values | array of integer | A list of score Available values: from 1 to 10. 1: Lowest, 10: Highest. |
Required |
| data.operator | string | in: Select songs whose score is in the list. not_in: Exclude songs whose score is in the list. | Required |
| AttributName | Object type | Description | Additional |
|---|---|---|---|
| type | string | complexityScore Filter songs by complexity score identified in the lyrics. | Required |
| data | object | Required | |
| data.values | array of integer | A list of score Available values: from 1 to 10. 1: Lowest, 10: Highest. |
Required |
| data.operator | string | in: Select songs whose score is in the list. not_in: Exclude songs whose score is in the list. | Required |
| AttributName | Object type | Description | Additional |
|---|---|---|---|
| type | string | rhymeSchemeScore Filter songs by rhyme scheme score identified in the |
Required |
| data | object | Required | |
| data.values | array of integer | A list of score Available values: from 1 to 10. 1: Lowest, 10: Highest. |
Required |
| data.operator | string | in: Select songs whose score is in the list. not_in: Exclude songs whose score is in the list. | Required |
| AttributName | Object type | Description | Additional |
|---|---|---|---|
| type | string | repetitivenessScore Filter songs by repetitiveness score identified in the lyrics. |
Required |
| data | object | Required | |
| data.values | array of integer | A list of score Available values: from 1 to 10. 1: Lowest, 10: Highest. |
Required |
| data.operator | string | in: Select songs whose score is in the list. not_in: Exclude songs whose score is in the list. | Required |
Request
POST /api/v2/top/songs
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 Song collection reponse |
TopSongCollectionResponse |
| 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. |