Get festivals
Get a list of festivals filtered by attributes and stats.
You can sort and filter festivals in our database using specific parameters such as social metrics, score, capacity or name.
These are the available metricType/platfom combinations used to sort and filter festivals:
- score: soundcharts
- followers: instagram, twitter, tiktok
- fans: facebook
- subscribers: youtube
- channelViews: youtube
- likes: twitter, tiktok
Sort
| Name | Value | Description | Additional |
|---|---|---|---|
| Sort | object | Sort festival by a metric (by total or change over a period) | Optional |
| type | string | Sort the list of venue by either:
Available values: metric, capacity, name |
Required |
| platform | string | Code of the platform used for the sorting metric. Find out the available platform in the description above. | Only if type is metric |
| metricType | string | Type of metric used for sorting the festival. Find out the available metricType per platform in the description above. |
Only if type is metric |
| sortBy | string | Sort the list of festival 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 and sortBy is not total |
| order | string | Available values: desc, asc | Required |
Filters
| AttributName | Object type | Description | Additional |
|---|---|---|---|
| type | string | metric Filter festivals by any metric |
Required |
| data | object | Required | |
| data.platform | string | Code of the platform used for the filtering metric. Find out the available platform in the description above. | Required |
| data.metricType | string | Type of metric used for filtering the festivals. Find out the available metricType per platform in the description 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: month, quarter |
Optional |
| data.changeType | string | Choose the type 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 | venueCountryCode Filter festivals by their country |
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 festivals where at least one country matches any of the specified options. not_in: Exclude festivals where at least one country matches any of the specified options. |
Required |
| AttributName | Object type | Description | Additional |
|---|---|---|---|
| type | string | festivalGenres Filter festival by genres | Required |
| data | object | Required | |
| data.values | array of strings | A list of festival genres. Find out the available list Get artist genres endpoint. |
Required |
| data.operator | string | in: Select festivals who have at least one of the specified genres. not_in: Exclude festivals who have at least one of the specified genres. |
Required |
| AttributName | Object type | Description | Additional |
|---|---|---|---|
| type | string | capacity Filter festivals by their capacity | Required |
| data | object | Required | |
| data.min | integer | Set the minimum capacity | At least one of the 2 values is mandatory |
| data.max | integer | Set the maximum capacity | At least one of the 2 values is mandatory |
| AttributName | Object type | Description | Additional |
|---|---|---|---|
| type | string | months Filter festivals by the months at which they take place | Required |
| data | object | Required | |
| data.values | array of strings | A list of months Available values: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12 | Required |
| data.operator | string | in: Select festivals which take place during one of the specified months. not_in: Exclude festivals which take place during one of the specified months. |
Required |
| AttributName | Object type | Description | Additional |
|---|---|---|---|
| type | string | isActive Filter festivals which either have an upcoming edition or had an edition in the past 12 months. |
Required |
| data | object | Required | |
| data.value | boolean | Available values: true, false | Required |
Request
POST /api/v2/top/festivals
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 festival collection response |
TopFestivalCollectionResponse |
| 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. |