Get venues
Get a list of venues filtered by attributes and stats.
You can sort and filter venues 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 venues:
- score: soundcharts
- followers: instagram, twitter, bandsitown, tiktok
- fans: facebook, vk
- subscribers: youtube
- channelViews: youtube
- likes: twitter, tiktok
Sort
| Name | Value | Description | Additional |
|---|---|---|---|
| Sort | object | Sort venue 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 venue. Find out the available metricType per platform in the description above. |
Only if type is metric and sortBy is not total |
| sortBy | string | Sort the list of venue 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 venues 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 venues. 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 venues 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 venues where at least one country matches any of the specified options. not_in: Exclude venues where at least one country matches any of the specified options. |
Required |
| AttributName | Object type | Description | Additional |
|---|---|---|---|
| type | string | venueGenres Filter venue by genres | Required |
| data | object | Required | |
| data.values | array of strings | A list of venue genres. Find out the available list Get artist genres endpoint. |
Required |
| data.operator | string | in: Select venues who have at least one of the specified genres. not_in: Exclude venues who have at least one of the specified genres. |
Required |
| AttributName | Object type | Description | Additional |
|---|---|---|---|
| type | string | capacity Filter venues 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 | isActive Filter venues 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/venues
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 venue collection response |
TopVenueCollectionResponse |
| 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. |