Based on simple REST principles, the Bandsintown Partner Search API endpoint returns JSON metadata about Artists, Events, and Venues.

With the Partner Search API, you can access data like:

Just Announced shows
Popular shows at a specific location
All shows or artists for a specific genre

The base URL of the Partner Search API is: https://search.bandsintown.com/search

Test the Partner Search API using the API key provided to you in the HTTP request header:

x-api-key: your-api-key

Rate limiting is applied as per application based on Client Key, and regardless of the number of users who use the application simultaneously.

Please keep in mind the API Terms of Use when utilizing the Partner Search API. In brief:

Ticket and RSVP links must be visible and clickable
You must properly display Bandsintown logos
You may not modify or remove the display of any trademarks
Session-based caching is acceptable but must be cleared in a timely manner
Do not share nor modify content
Do not scrape data

By using this API, you have accepted our Terms of Use. To read the full Terms of Use, click here.

Request: HTTP METHODE: GET

HTTP Query string parameters

Key

Value type

Value default

Value description

query

Query Object

(mandatory)

n/a

A JSON object, URL encoded, containing the search parameters

user

User Object (optional)

-

A JSON object, url encoded, containing information about the user, needed to perform the search. Mandatory if location=user or if filter is set to recommended or “tracked artist”

entities

Array of Entity

Object

(mandatory)

n/a

List of top-level entities expected in the response.

term

String (optional)

-

Search term, entered by the partner in the search box

type

String (optional)

-

Possible values: "both", "streaming", and "physical"

scopes

Array of String

(optional)

[“artist”,”venue”]

Restrict search to these scopes of entity for a given term

Possible values: artist, event, venue, event_id

region

Region Object

(mandatory for

location: region)

n/a

Limit the search to this geographical

region (gps coordinates and radius).

Not applicable for artist.

genre

String (optional)

all

Limit the search to a genre of music.

Possible values:
See table below.
Not applicable for venue search

Genre	Slug
Alternative	alternative
Blues	blues
Christian/Gospel	christian-gospel
Comedy	comedy
Country	country
Classical	classical
Electronic	electronic
Folk	folk
Gamers	gamers
Hip Hop	hip-hop
Jazz	jazz
Latin	latin
Metal	metal
Podcast	podcast
Pop	pop
Punk	punk
R&B/Soul	rnb-soul
Reggae	reggae
Rock	rock

genres

Array of String
(optional)

-

Limit the search to a list of genres of music.

Possible values:
See table in genre section above.
Not applicable for venue search
If genre and genres are specified at the same time,
genre is used

tag

String (optional)

-

Limit the search to entities containing this tag

(promotional or editorial usage).
Only applicable to event or artist search

filter

String (optional)

-

Limit or enlarge the search to a user specified criteria.

Possible values:
For artist search: “on tour”

period

Period Object

(optional)

-

Limit the search to a range of dates.
Only applicable to event search

Region Object

Key	Value type	Value default	Value description
place	String (optional)	-	Name of the region, such as the city name (San Diego, CA). Not actually used by the search API.
latitude	Double(mandatory)	n/a	Latitude coordinate WGS84 format
longitude	Double(mandatory)	n/a	Longitude coordinate WGS84 format
radius	Double (mandatory)	n/a	Radius in miles for the lat/long center (imperial miles). Max allowed value is 200.

Period Object

Key

Value type

Value default

Value description

starts_at

String(optional)

request.local_time

Start date and time in ISO 8601 format, in the timezone of

the request (local time). Format not ending with a Z is also

supported.

ends_at

String(optional)

distant future

End date and time in ISO 8601 format, in the timezone of the

request (local time). Format not ending with a Z is also

supported.

relative_to

String(optional)

“all dates”

Define the time period based on the actual time in the timezone of the request. Possible values are:

Value	Starts at	Ends at
“all dates”	request.local_time	Distant future
“tonight”	Today 4pm	Tomorrow 2am
“tomorrow”	Tomorrow 0am	Day after tomorrow 2am
“this weekend”	This Friday 4pm	Next Monday 2am
“next week”	Next Monday 0am	Following Monday 2am
“next month”	1st day of next month at 0am	1st day of the month after next at 2am
"now"	Starting between now and now + 5 minutes	OR It already started and won’t end in the next 15 minutes

local_time

String

(optional)

-

This is the time zone provided by the request

Example: “local_time”: “2020-06-15T14:05:00-04:00”

Entity Object

Key	Value type	Value default	Value description
type	String (mandatory)	n/a	Type of main level entity objects expected in response. Possible values: artist, event, venue
order	String (optional)	trackers for artist rsvps for event distance for venue	Order of the entity objects in the response. Possible values: name (asc), trackers (desc) for artist, “start date” (asc), “announcement date” (desc), “on sale date” (asc), rsvps (desc) or “artist name” (asc) for event name (asc) or distance (asc) for venue
limit	Integer (optional)	100	Limit the number of entity objects to be sent in the response. Max allowed value is 200.
offset	Integer (optional)	0	Offset of the first entity object to be sent in the response. If offset is given (could be 0), the response will contain the pagination information. Max allowed value is 1000.

Fields in response for top level entities:

Fields for Artist:

Name	Value type	Value description
id	Integer	Id of the artist
name	String	Name of the artist
tracker_count	Integer	Number of trackers for the artist
on_tour	Boolean	Indicate if the artist is on tour (i.e.: has upcoming events)
genres	Array of String
links	Array of String	Links to socials
bio	String
image_url	String	Public URL of the image
track_url	String	URL to trigger a track for this artist
artist_url	String	URL for that artist

Fields for Venue:

Name	Value type	Value description
id	Integer	Id of the venue
name	String	Name of the venue
address	String
latitude	Double	Latitude coordinate WGS84 format
longitude	Double	Longitude coordinate WGS84 format
location	String	Location of the venue. The format is either “City, Country” for non US venues, or “City, State” for US venues. E.g.: Los Angeles, CA or Berlin, Germany
image_url	String	URL for an image relative to this venue. Optional

Fields for Events:

Name	Value type	Value description
id	Integer	Id of the event
title	String (optional)
description	String (optional)
starts_at	String	Date/Time when the event starts i.e.: "2017-04-21T19:00:00"
venue_id	Integer	The venue ID
artist_id	Integer	Leading Artist ID
lineup	Array of Integers	An array of artist ID’s in the lineup
ticket_available	Boolean	This indicates if there are ticket links available
rsvp_count	Integer	Amount of users who have RSVP’d to the event
image_url	String	URL of the image
rsvp_url	String	URL to trigger a RSVP on the event
event_url	String	URL for that event
ticket_url	String	URL for tickets for this event
timezone	String	The time zone used for live streaming events, i.e. "America/Los_Angeles"
streaming_event	Boolean	To indicate if it is a live streaming event or not

Query examples

Term search in San Diego, CA:

Jazz events search in San Diego,CA search

Events next weekend In San Diego, CA search

{
"term": "John",
"location": "region",
"region":
{
"latitude": 32.71515,
"longitude": -117.15653,
"radius": 50
},
"entities":
[

{
"type": "artist",
"order": "trackers",
"limit": 4
},
{
"type": "event",
"order": "rsvps",
"limit": 4
},
{
"type": "venue",
"limit": 4
}
]
}

{
"genre": "jazz",
"location": "region",
"region":

{
"latitude": 32.71515,
"longitude": -117.15653,
"radius": 50
},
"entities":

[

{
"type": "artist",
"order": "trackers",
"limit": 4
},

{
"type": "event",
"order": "rsvps",
"limit": 4
}

]
}

{
"period":

{
"starts_at": "2021-02-17T19:00:00Z",
"ends_at": "2021-02-20T06:00:00Z"
},
"location": "region",
"region":

{
"latitude": 32.71515,
"longitude": -117.15653,
"radius": 50
},
"entities":

[{
"type": "artist",
"order": "trackers",
"limit": 4},

{

"type": "event",
"order": "rsvps",
"limit": 4
}]
}

Response:

HTTP Status:

Status Code	Status Message	Reason
200	OK	Responds with a list of entity objects or an empty list
400	Bad Request	Something is wrong with the request parameters
401	Unauthorized	The Authorization header is missing, invalid or doesn’t match user information
500	Internal Server Error	The API server crashes
501	Not Implemented	The search API doesn’t implement yet the set of request parameters
504	Gateway Time-out	The API server took too long to return a response

Embedded resources:

When event entities are requested as a top-level response, the embedded resources should include the artist entity and venue entity objects associated to each events except if those entities are already returned as top-level entity objects.

Examples of how to use the partner search api

Authentication:

Key: x-api-key

Value: yOUrSuP3rP4RtneRaPI-K3y

Add to: Header

1. Single Entity with Pagination

Entity: Artist

Pagination: Limit 2 and Offset 0

https://search.bandsintown.com/search?query={"entities":[{"type":"artist","order":"trackers","limit":2,"offset":0}],"term":"Lady","scopes":["artist"]}

Result:

2. Retrieve Multiple Entities

Entities: Artists and Events

https://search.bandsintown.com/search?query={"entities":[{"type":"artist","order":"trackers","limit":2,"offset":0}],"term":"Lady","scopes":["artist"]}

Result:

3. Retrieve an specific event

Entity: Event

https://search.bandsintown.com/search?query={"entities": [{"type": "event"}], "term":102617588, "scopes":["event_id"]}

Result:

4. Search Event by Artist ID

Entity: Event

https://search.bandsintown.com/search?query={"entities":[{"type":"event", "order":"rsvps","limit":4}],"term":"22741","scopes":["artist_id"]}

Result:

5. Search venues by name OR BY ID

Entity: Venue

Search by Venue Name

https://search.bandsintown.com/search?query={"entities": [{"type": "venue"}], "term":"Bell Centre", "scopes":["venue"]}}

Search by Venue ID

https://search.bandsintown.com/search?query={"entities":[{"type":"venue"}],"term":10003087,"scopes":["venue_id"]}

Result:

6. Search Venue by Name and Location

Entity: Venue

https://search.bandsintown.com/search?query={"entities": [{"type": "venue"}], "term":"Bell","region":{"place":"Montreal"}}

Result:

7. Search Events by Venue ID

Entity: Event

https://search.bandsintown.com/search?query={"entities": [{"type": "event"}], "term":10003087, "scopes":["venue_id"]}

Result:

8. Search Artists who played in a specific venue (venue ID)

Entity Event

https://search.bandsintown.com/search?query={"entities": [{"type": "event"}], "term":"10003087", "scopes":["venue_id"]}}

Result:

9. Search Events and Artists who played in a specific venue by (venue ID) and genre

Entity Event

https://search.bandsintown.com/search?query={"entities": [{"type":"event"}], "term":"10003087", "genre":"pop"}

Result:

10. Search Events by GPS Coordinates and Genre

Entity Event

https://search.bandsintown.com/search?query={"entities": [{"type": "event"}], "region": {"latitude": 45.496112, "longitude":-73.569315, "radius":50},"genre":"pop"}}

Result:

11. Search LIVE streaming Events

Entity Event

https://search.bandsintown.com/search?query={"entities": [{"type": "event"}], "term":"jason wild", "type":"streaming"}

result:

12. Search LIVE streaming Events by genre

Entity Event

https://search.bandsintown.com/search?query={"entities": [{"type": "event"}], "type":"streaming","genre":"latin"}

result:

13. Search PHYSICAL Events, last modified IN A PERIOD OF TIME, orderED by start date

Entity Event

https://search.bandsintown.com/search?query={  "entities": [{"type": "event","order":"start_date","limit":199,"offset":0}],  "term":"2021-08-20T00:00:00ZTO2021-08-23T00:00:00Z","scopes":["last_modified_time"], "type": "physical"}

result:

The result is divided into three sections.

Events, embedded Artists, and embedded Venues

In this way, you won’t need to do another query to retrieve the artist’s bio, tracker_count, venue address, venue latitude and longitude, and more.

Share your feedback | Join our community

PARTNER SEARCH API

Table of contents

API Structure and objects

Examples of how to use the partner search api

Request: HTTP METHODE: GET

Region Object

Period Object

Entity Object

Fields in response for top level entities:

Fields for Artist:

Fields for Venue:

Fields for Events:

Query examples

Response:

HTTP Status:

Embedded resources:

Examples of how to use the partner search api

Authentication:

1. Single Entity with Pagination

Result:

2. Retrieve Multiple Entities

Result:

3. Retrieve an specific event

Result:

4. Search Event by Artist ID

Result:

5. Search venues by name OR BY ID

Result:

6. Search Venue by Name and Location

Result:

7. Search Events by Venue ID

Result:

8. Search Artists who played in a specific venue (venue ID)

Result:

9. Search Events and Artists who played in a specific venue by (venue ID) and genre

Result:

10. Search Events by GPS Coordinates and Genre

Result:

11. Search LIVE streaming Events

result:

12. Search LIVE streaming Events by genre

result:

13. Search PHYSICAL Events, last modified IN A PERIOD OF TIME, orderED by start date

result: