API

Welcome developers!

If you want to access our extensive database of events then the Evently API is for you! Integrate our API easily into your website or application and start building cool products with our events data.

Check out our documentation and apply for an API key. We’ll be in touch soon so that you can get coding!

API Documentation

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

What is the Evently API?

The Evently API allows website owners to add Evently events content to their website. Evently 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.

1. Technical Details

Our API is accessible via HTTP, 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, whereas 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.event.ly/v3/events.json?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.event.ly/v3/events.json
GET http://api.event.ly/v3/events.xml

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

GET http://api.event.ly/v3/events?format=json
GET http://api.event.ly/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.event.ly/v3/venues/search.json?city=London
GET http://api.event.ly/v3/venues/search.json?city=London&page=2
GET http://api.event.ly/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.

2. 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

Which 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.event.ly/v3/genres/2/events.xml

Required parameters: genreid and apikey

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.

3. 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.

4. Getting a specific venue by it's UUID

GET /v3/venues/<venue-UUID> Returns a single venue by its UUID.

Example venue response

5. 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/ Returns the Event that matches the UUID provided.

GET /v3/genres/events Returns the next 100 events within a particular genre.

GET /v3/venues/events Returns the next 100 events at a particular venue.

6. Example Event Usage

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

http://api.event.ly/v3/venues/911bf810-d21b-012e-832d-123142ff4e0c/events?format=json