Bullseyehub is becoming Evently. Everything you loved about Bullseyehub is still here - but we're making it even better. Find out more or get in touch.

Bullseyehub

Call +44 (0)20 7713 6642
login

Support Everything you need to know about using Bullseyehub

API Documentation

Find out how the API works and start adding Bullseyehub events content to your website.

What is the Bullseyehub API?

The Bullseyehub API allows website owners to add Bullseyehub events content to their website. Bullseyehub events data comes from some of the industry’s top venues and promoters. We give you access to over 1,000 unique event listings each month. You can use our API to display events by genre, venue or even geographic location.

Technical Details

Our API is accessible via HTTP and HTTPS, is RESTful, and offers both JSON and XML response formats (find the schemas below). All data responses are UTF-8 encoded.

You must pass your API key as a parameter to every request you make.

Only details on future events are available.

Times and dates are provided in UTC timezone and are in in ISO 8601 format.

We use a combination of IDs and UUIDs to identify resources. Genres have an ID, where as Events and Venues have UUIDs.

API Key

When accessing the API you will need to provide your API key. You can do this via a GET parameter like so:

GET http://api.bullseyehub.com/v3/events?api_key=<your_api_key>

Or if you prefer, you can pass the API key within the Authorization header.

Get your free API key here.

Response Formats

We can render responses for you using JSON or XML.

In order to specify your choice of response format you can append .json or .xml to the request path like so:

GET http://api.bullseyehub.com/v3/events.json
GET http://api.bullseyehub.com/v3/events.xml

You can pass a format parameter along with your GET request:

GET http://api.bullseyehub.com/v3/events?format=json
GET http://api.bullseyehub.com/v3/events?format=xml

Or you can use an Accept header.

Pagination

Results are returned 100 elements at a time. To get subsequent elements use the page parameter as follows:

GET /v3/<element>.<format>?page=<page-number>

Pagination is enabled on all API resources.

Pagination usage example: Get the first 300 venues in London as JSON (remember to add your API key):

GET http://api.bullseyehub.com/v3/venues/search.json?city=London
GET http://api.bullseyehub.com/v3/venues/search.json?city=London&page=2
GET http://api.bullseyehub.com/v3/venues/search.json?city=London&page=3

How to fetch the event data you want!

You can fetch event data from our API based on Genre, Venue or even geographic location.

How to fetch events by Genre

Method: Events by genre ID

You can fetch the available genres and their associated ID using the following endpoint:

GET /v3/genres

Returns a list of all genres.

Example Response containing all Genres

Use the genre ID to return all future events of a particular genre (in pages of 100) as XML

URL: http://api.bullseyehub.com/v3/genres/2/events.xml

Required parameters: genre_id and api_key

Optional parameters: page (Page of result you wish to look at. 100 events per page. Defaults to page 1)

Allowed values: Positive integers - a HTTP 204 Status code will be returned if the page contains no venues.

How to fetch events by Venue

First you need to find the venue UUID you're interested in.

You can search for a venue by longitude and latitude, and by the presence of a word in any or all Venue fields.

Method: Venue search by field

To find any venue in north-west London with a name that contains Jazz.

GET /v3/venues/search.json?name=Jazz&lat=51.5&lng=-0.1

To find any venue with a postcode that contains the word EC2.

GET /v3/venues/search.json?postcode=EC2

To find any venue with the string "Chocolate Rain" anywhere in it's address or name (note, parameters need to be URL encoded).

GET /v3/venues/search.json?q=Chocolate%20Rain

Available search parameters

q	Finds any venue with all of the query string within the Venue's name and address.
lat	When used in combination with `lng` finds any venue within a small distance of the provided latitude and longitude.
lng	When used in combination with `lat` finds any venue within a small distance of the provided latitude and longitude.
precision	When used in combination with `lat` and `lng` can be used to increase or decrease the surrounding area considered to be a match. Use of precision comes from Geohashes, which are generated automatically for all Venues. The larger the precision value, the smaller the area.
street	Finds any venue with a street that contains all of the value provided.
city	Finds any venue with a city that contains all of the value provided.
area	Finds any venue with an area that contains all of the value provided.
country	Finds any venue with a country that contains all of the value provided.
postcode	Finds any venue with a postcode that contains all of the value provided.

Getting a specific venue by it's UUID

GET /v3/venues/<venue-UUID>

Returns a single venue by it's UUID.

Example Venue response

Other Available Endpoints

GET /v3/events	Returns the next 100 events. Events in the past will not be returned by default but can always be found by visiting an event directly.
GET /v3/events/<event_uuid>	Returns the Event that matches the UUID provided.
GET /v3/genres/<genre_id>/events	Returns the next 100 events within a particular genre.
GET /v3/venues/<venue_uuid>/events	Returns the next 100 events at a particular venue.

Example Event Usage

Get the first 100 events at Purple Turtle as JSON (remember to add your API key):

http://api.bullseyehub.com/v3/venues/911bf810-d21b-012e-832d-123142ff4e0c/events

Example Event response

Sitemap

What is Bullseyehub?

Bullseyehub is event promotion software, which combines automatic event listings, email, mobile and social tools that make it easy to promote events online.

Bullseyehub is perfect for music promoters, bars & clubs, arts organisations, restaurants, hotels, conferences, community groups and event organisers who use our tools to promote their events online.