The Eventotron API allows you to pull all the information you need about your festival out of Eventotron and into your other platforms, like your website or app. We can also pass all the info you need to link up your events to your box office and, if you are using Super Simple Box Office, you can even use it to sell tickets.
Only finalised events are available through the API. You can remove a particular finalised event from the API by going to that show’s ‘Office Use’ section and setting ‘Show on Website’ to ‘No’.
There are three different approached to using the API:
The Big Dump
Best suited to large festivals. Your website or app talks to Eventotron on a regular basis and grabs all the data about your events and venues in one big bundle. Your website or app is then responsible for crunching all the data and performing searching and filtering for end users.
Use this for: Total flexibility of how you present your shows, control over the performance of your site, integration with other services.
You will need: A developer, your own well-provisioned web server, plenty of time.
Live Integration
Instead of copying everything to your website every few hours, your website talks to Eventotron live whenever it needs information. Eventotron handles all the searching and filtering for you and your data is never out of date.
Use this for: Getting your integration up and running quickly, staying bang up to date, ease of use for festival administrators. Control over how your events are presented to users.
You will need: A developer, a server, some time.
WordPress
This is the out of box solution for total ease of use and quick, extremely low cost setup. Install a WordPress Plugin on your existing website, pop in an API key and your shows are instantly available and searchable. With Super Simple Box Office, you can even turn on ticket sales with one click.
Use this for: Ease and speed.
You will need: A WordPress based website and about four minutes.
Please note the plugin is available to existing Eventotron clients only. If you would like access, please email wordpress@eventotron.com
IMPORTANT: For developers and designers working on behalf of a mutual client please request the plugin via your client in the first instance.
Setting Up the API Output
Whichever method of integration you choose, you’ll need to specify what data comes out of the API. By default, the API will output your event names, performance dates times and prices and venue details. If you need to send other information from your questionnaires to your websites or apps, you need to tell Eventotron. It’s easy – just go to ‘Info Collection’ in your Festival’s Management Console. Find the question you want exposing to your website and set ‘Appears Online’ to ‘Yes’. This will make sure the information is available online. It also displays a little icon next to the question when artists are viewing it so they know this info will be publicly available.
There’s one more step that’s useful to know about. If you click on ‘Advanced’, you’ll see a question called ‘API Field Name’. By default, the info will come through the API with the field name that Eventotron uses behind the scenes. This might not always be easily readable and, depending on how much chopping and changing you’ve done, might not obviously relate to the question any more. Fill in the ‘API Field Name’ to ensure it comes through in the API sensibly named. Your developer will thank you for it. Please use only letters, numbers and underscores – no spaces or punctuation.
Generate an API Key
An API Key is a bit like a password. Generate an API Key for each service that you want to share Eventotron Data with. That way you can turn individual services off without disturbing others if you need to. Your developer will need an API key. If you’re using our WordPress integration, you’ll need to pop the API key into the WordPress Plugin.
Generate API keys in Festival Management -> API Keys
Getting Data Out
Now that you’ve set up the output and generated an API key, you can start getting data out. The Eventotron API delivers data in JSON format. The simplest way to test it is just put one of the links below into your web browser, with your API key in place of [API KEY HERE]. You can install a JSON viewing plugin for your browser to make the output more readable.
There are several ‘endpoints’ you will use to get data out of Eventotron. The first one to experiment with is the ‘Season’ endpoint – this gives a summary of your festival, including all the events and venues taking part, and explains what data you have made available to the API.
https://www.eventotron.com/api/season.php?apikey=[API KEY HERE]
The next endpoint might be all you need if you’re using the ‘Big Dump’ method of integration as it supplies details of all your events, including their dates, times and prices and a summary details of the venues they are on in:
https://www.eventotron.com/api/shows.php?apikey=[API KEY HERE]
To avoid having to re-download all the data each time you hit the API, you can use the ‘Updated Shows API’:
https://www.eventotron.com/api/showupdates.php?apikey=[API KEY HERE]
This will give you a list of Eventotron IDs for shows that have been changed since the endpoint was last hit. Add ‘&test’ to get some random shows back.
You would then hit the Single Show endpoint to get those updated shows:
https://www.eventotron.com/api/show.php?apikey=[API KEY HERE]&show_id=[EVENTOTRON EVENT ID HERE]
Finally, for more detailed information about the venues in your festival, use this endpoint:
https://www.eventotron.com/api/venues.php?apikey=[API KEY HERE]
The Search Endpoint
Use this to return a sub-set of the events in your season or festival based on anything in your questionnaires, venue info or dates, times and prices of events, depending on what you want to display or conditions a user may have entered in your website’s search form. You can also specify exactly which fields are returned by this endpoint.
Using a combination of the Search Endpoint and the Single Show endpoint is how you achieve a fully live integration, handing over the storing, caching, searching and filtering of data to Eventotron.
Use of the Search Endpoint is currently subject to load restrictions. If you are interested in using it please contact api@eventotron.com
Other useful info:
Images
If you are exposing images in your API, you will not be sent the raw data but, instead, a URL for the image at IMGIX, a distribution network that hosts all images uploaded to Eventotron. You are free to use these images directly (although this may be subject to extra charges in future).
By default the image URL provided by Eventotron will give you the full size image. IMGIX gives you access to several powerful tools and filters to crop, resize and edit any images by appending commands to the URL. This is great for creating thumbnails or even clever things like zooming in on faces or changing colour temperature. All without putting any load on your server. These features are available free to all Eventotron clients.
Find out more at https://www.imgix.com/
Ugly Endpoints
We know the URLs of our endpoints don’t look very nice. Sorry. We’ll tidy this up in future but will leave the endpoints described here live.
Box Office Integration
Super Simple Box Office is Eventotron’s built-in box office solution, designed for smaller festivals without a box office manager. It allows super simple setup and keeps things like box office reports and comp issuing within Eventotron for easy access by your artists. It will even payout automatically if you want it to. Its functionality is available through the API and the WordPress Plugin. If you would like to know more please email ssbo@eventotron.com
Many larger festivals, or those who want the flexibility of a full strength box office, will be using an outside box office provider. This might be a good time to think about how you can integrate other Box Offices with Eventotron.
Use Eventotron’s API or your Box Office Provider’s?
Your box office provider probably offers their own API to get your ticket sales onto your website. Alternatively they may set up another website that they host and that you link to when you want to send a customer off to buy tickets. Both these approaches are totally valid and might suit you well. In this case you would use Eventotron to collect the information about your festival and then export it from Eventotron (we have tools that make this as easy as possible, depending on what options your Box Office Provider has for importing the data).
There are some disadvantages to the above, though:
You can only use the data you have put in the box office; this might not include all the rich information you or your artists have put into Eventotron like images, files, custom questions, press reviews etc.
Typically your artists (or more likely your venue managers) will not have access to make corrections and changes so will need to contact your box office manager by email or phone to alert of performance changes, special offers etc.
You end up with two sets of data (Eventotron and Box Office) which need to be manually kept in sync.
We therefore recommend you use a combination of the Eventotron API and your Box Office provider’s. This allows you to maintain all the depth of information stored in Eventotron and the direct communication with your stakeholders, while harnessing the power and flexibility of full strength box office.
This is the approach used by some of Eventotron’s larger festivals (Brighton, Melbourne and Wellington Fringes, for example, and the EdFest app used by Assembly, Gilded Balloon, Pleasance and Underbelly). It’s invisible to the ticket buyer and not as complicated as it might sound. Here’s how it works…
After you have exported your event information to your box office, Eventotron connects directly to the Box Office’s API and automatically finds and stores IDs for all the performances in the Box Office. We call this process ‘box office pullback’.
Eventotron then makes these performance ID’s available through its own API.
When a ticket buyer browses your website, they are looking at data held in Eventotron and exposed by the Eventotron API (that data has found its way to your website through a Big Dump or a Live Integration). This data includes loads of info about the event including when and where it’s on and how much it costs. When a user wants to buy a ticket, your website uses the relevant performance ID that it has got from Eventotron to talk to your Box Office’s API and discover availability and, in some cases, more complex pricing information. Your website can then continue talking to the box office handle a shopping basket and complete the sale.
Any changes needed can be done in Eventotron by festival or venue staff and even (if you allow them) artists and producers. If these changes affect dates times and prices, Eventotron will try to push them to the Box Office. However, some box offices only allow a one-pff import of data rather than live changes from another service. Int his case, the performance change would be done in the Box Office software and Eventotron will quietly chug away in the background, talking to the Box Office API and syncing back any changes so it stays up to date (that’s really useful if you want to use any of Eventotron’s post-festival functions like settlement sheets and payouts.).
We hope this document has given you an insight into the various ways you can use Eventotron’s API and how to integrate it with other services. Please contact api@eventotron.com with any questions or suggestions.
