Table of Contents
Some Basic Terminology
The Ticket Evolution API includes Performers, Venues, Configurations, Events, and Ticket Groups.
Performers
Performers are an entity who will be playing/competing/performing at the Event. A performer could be a
- Band (Guns ‘N’ Roses)
- Team (New Orleans Saints)
- Individual musician (Billy Joel)
- Speaker (Dave Ramsey)
- Comedian (Amy Schumer)
- Annual Event (Kentucky Derby)
- Play/Musical/Theatrical Performance (Hamilton)
Venues
Venues are the specific locations where an event/game/performance takes place. Some examples:
- Madison Square Garden
- Fenway Park
- Mercedes-Benz Superdome
Configurations
Venues have one or more configurations which is a layout or stage setup for particular events such as sports, concerts, or even specific concert tours where the stage is a custom layout. Each configuration will include a static seating chart.
Events
Events are the individual performances/competitions for which you are buying/selling tickets. Every event includes at least one Performer (but may have many) at a single Venue at a specific time (the {{occurs_at}} property). When an event is a game the “home team” Performer will be marked as primary and the “away team” will not. When an event is a concert with multiple bands/musicians the “headliner” will be marked as primary and any “opening bands” will not.
Some events may include a performer that is also the name of the event. An example of this is the Super Bowl. All year long the Super Bowl event will have a single Performer named Super Bowl, but as the teams that will be playing are decided they will be added to the event resulting in having three Performers attached to the event: Atlanta Falcons (primary since they were designated as the “home team”), New England Patriots, and Super Bowl.
Ticket Groups
Ticket Groups are collections of adjacent seats owned by the same supplier and could there be a single ticket or dozens of tickets within that ticket group. The cost of each ticket within the ticket group is the same and all seats purchased from the ticket group will be adjacent.
See
Listing Events Near Your Visitors
Many sites include a list of upcoming events near the visitor based on geolocation of the visitor’s IP address. The Events / Index endpoint accepts several different options for location but the recommended one is to send lat and lon of the visitor along with a within radius for the venues.
curl -i \ -X GET \ -H "X-Signature: 5tsKHA+v8xm3HPPqcG9rNhu7+GqYB4N77tTk7tr/FKQ=" \ -H "X-Token: SabreHackathon:TTX2017LasVegasNV" \ --url 'https://api.sandbox.ticketevolution.com/v9/events?lat=36.1207804&lon=-115.156559&order_by=events.occurs_at&page=1&per_page=10&within=20'
$response = $client->listEvents([
'page => 1,
'per_page => 10,
'lat => 36.1207804,
'lon => -115.156559,
'within => 20,
'order_by' => 'events.occurs_at',
]));
@event = @connection.events.list({
'page => 1,
'per_page => 10,
'lat => 36.1207804,
'lon => -115.156559,
'within => 20,
'order_by' => 'events.occurs_at',
})
Comprehensive Search
Every site should have a comprehensive search available on most every page including possibly making it the main feature of the homepage. Once a visitor is has selected an event for which to view tickets and throughout the purchase process it probably makes sense to not show the search and instead use that space for useful elements.
It is suggested that this main search performs a search across Performers, Venues, and Events.
Comprehensive Search can be done via two different endpoints and you should experiment with both and decide which you prefer based on the experience you choose to present to the user.
/searches/suggestions
The /searches/suggestion endpoint was created to be used in an auto-suggest type of selector.
curl -i \ -X GET \ -H "X-Signature: IKE8qY1xcCqHKoJFOC+Ett/Xpy5pzkXdCRQh5YflTCs=" \ -H "X-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \ --url 'https://api.ticketevolution.com/v9/searches/suggestions?entities=events,performers,venues&fuzzy=true&limit=6&q=diamondbacks'
$response = $client->listSearchSuggestions([
'entities' => 'events,performers,venues',
'fuzzy' => true,
'limit' => 6,
'q' => 'diamondbacks',
]));
@search = @connection.searches.suggestions({
'entities' => 'events,performers,venues',
'fuzzy' => true,
'limit' => 6,
'q' => 'diamondbacks'
})
curl -i \ -X GET \ -H "X-Signature: SAk9DIBXiITAJzwmx5RmTDEEqpGzxsGXh4QNSWB4Jig=" \ -H "X-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \ --url 'https://api.ticketevolution.com/v9/search?order_by_popularity=true&page=1&per_page=6&q=diamondbacks&types=events,performers,venues'
$response = $client->search([
'order_by_popularity' => true,
'page' => 1,
'per_page' => 6,
'q' => 'diamondbacks',
'types' => 'events,performers,venues',
]);
@search = @connection.search.list({
'order_by_popularity' => true,
'page' => 1,
'per_page' => 6,
'q' => 'diamondbacks',
'types' => 'events,performers,venues'
})
Performer Landing Page
Each performer should have their own “landing page” which includes information about that performer and shows any upcoming Events for that performer. Because the Ticket Evolution catalog includes over 45000 Performers, these pages are dynamically created and usually use the slug property of the Performer to create the URL. In the case of the Arizona Diamondbacks the slug is arizona-diamondbacks and your URL might look something like www.myawesometicketsite.com/arizona-diamondbacks-tickets
To generate such a page you should retrieve the Performer slug from the URL, which in the example of www.myawesometicketsite.com/arizona-diamondbacks-tickets would be arizona-diamondbacks. Then two API requests are made, the first one being Performers / Show in order to retrieve information about the performer.
curl -i \ -X GET \ -H "X-Signature: Eha/EE1EbP8mYqmf72AYOq0ee641Y/Q6EoRgDGv1+zM=" \ -H "X-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \ --url 'https://api.ticketevolution.com/v9/performers/arizona-diamondbacks?'
$response = $client->showPerformer([
'performer_id' => 'arizona-diamondbacks',
]);
@performer = @connection.performers.show('arizona-diamondbacks')
After making the Performer / Show API request the id of the Performer (15556 in this example) can be used to display upcoming Events using the Events / Index endpoint.
curl -i \ -X GET \ -H "X-Signature: oy8oDMMfSjCoz6R3oWsE5/2CsKYlypgnHbL9YtDLUAo=" \ -H "X-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \ --url 'https://api.ticketevolution.com/v9/events?page=1&per_page=2&performer_id=15556'
$response = $client->listEvents([
'performer_id' => (int)15556,
]);
@event = @connection.events.list({
'performer_id' => 15556
})
Venue Landing Page
Many sites also choose to build a landing page for each venue (there are over 13,000 venues available via our API).
These pages are generated very similarly to the Performer Landing Pages using the Venue slug from the URL, which in the example of www.myawesometicketsite.com/venues/chase-field-tickets would be chase-field. Then two API requests are made, the first one being Venues / Show in order to retrieve information about the performer.
curl -i \ -X GET \ -H "X-Signature: Vmv9v4xDs/0QRNqLWmhT5sjqeoF08Kcxrjcbs9tvP6M=" \ -H "X-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \ --url 'https://api.ticketevolution.com/v9/venues/chase-field?'
$response = $client->showVenue([
'venue_id' => 'chase-field',
]);
@venue = @connection.venues.show('chase-field')
After making the Venues / Show API request the id of the Venue (110 in this example) can be used to display upcoming Events using the Events / Index endpoint.
curl -i \ -X GET \ -H "X-Signature: D/OPdqD6qrr1O5nLmvYNArnn9MxyuhDZQh8wf8Ho9Qk=" \ -H "X-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \ --url 'https://api.ticketevolution.com/v9/events?page=1&per_page=2&venue_id=110'
$response = $client->listEvents([
'venue_id' => (int)110,
]);
@event = @connection.events.list({
'venue_id' => 110
})
Event Landing Page
The Event page is where the consumer will select the tickets they wish to purchase. It generally includes a listing of all the available Ticket Groups as well as a seating chart image. Static seating chart images are included with API access and can be retrieved using URLs supplied in the response from the Events / Show endpoint which should be used first to retrieve the information regarding the Event including the Venue at which it occurs, the time (occurs_at), and the Performers which are scheduled to be at the Event.
curl -i \ -X GET \ -H "X-Signature: dGlJTI4UBJpZKTMVln/LZqblNM6GHTQahx+omG6lYEk=" \ -H "X-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \ --url 'https://api.ticketevolution.com/v9/events/1074357?'
$response = $client->showEvents([
'event_id' => (int)1074357,
]);
@event = @connection.events.show(1074357)
After making the Events / Show API request use the Ticket Groups / Index endpoint to display all the available Ticket Groups. You should always use lightweight=true with the /ticket_groups endpoint.
If you wish to display a static seating chart for the event you can find URLs for medium and large images under venue->configurations→seating_chart (e.g.:
https://s3.amazonaws.com/media.sandbox.ticketevolution.com/configurations/default_maps/ga_1000.jpg)
In Sandbox you need to change the /media.sandbox.ticketevolution.com/ portion of the URL to /media.ticketevolution.com/
curl -i \ -X GET \ -H "X-Signature: aUIDfd+u7mA9xp7iGbY6xIx7ZOGD0Qcb99bDkMKwtgY=" \ -H "X-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \ --url 'https://api.ticketevolution.com/v9/ticket_groups?event_id=1074357&lightweight=true'
$response = $client->listTicketGroups([
'event_id' => (int)1074357,
'lightweight' => true,
]);
@ticket_group = @connection.ticket_groups.list({
'event_id' => 1074357,
'lightweight' => true
})
Ticket Group Properties
| Property | Details | |||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
id | The unique ID of this ticket group. | |||||||||||||||||||||||||||||
type | Either event or parking to indicate which type of ticket this is. parking tickets do not include admission to the event but are great add-on item to suggest to a visitor purchasing event tickets | |||||||||||||||||||||||||||||
section | Indicates where seats are located. | |||||||||||||||||||||||||||||
row | ||||||||||||||||||||||||||||||
available_quantity | This is how many total tickets are available from this ticket group. | |||||||||||||||||||||||||||||
splits | An array of the quantities that may be purchased from this ticket group. Orders for quantities that are not in this array may be rejected. If you are building a <select> element for the user to choose the quantity they wish to buy you should populate the <option>s with these values. | |||||||||||||||||||||||||||||
wholesale_price | This is your cost for each ticket from this ticket group. When you submit an order the price you submit must be at least this much or the order will error. If you need to sell tickets below your cost you should use the discount parameter when placing your order. | |||||||||||||||||||||||||||||
retail_price | This is wholesale_price with any inventory rules applied. you are not required to charge your customer this amount. If you wish to handle retail price calculation on your side you may. | |||||||||||||||||||||||||||||
expected_delivery_type | This explains how it is expected that the ticket will be delivered to the Client. See the table below for more details. | |||||||||||||||||||||||||||||
format | Legacy indicator of the format of the ticket. One of: Paperless, GuestList, FlashSeats, TMMobile, Flash_seats, Guest_list, Tm_mobile. After July 2017 you should use format_new instead. | |||||||||||||||||||||||||||||
format_revised | Indicator of the format of the ticket. If there are certain types of formats or
| |||||||||||||||||||||||||||||
in_hand and in_hand_date |
If | |||||||||||||||||||||||||||||
instant_delivery | A boolean value that indicates whether or not you can expect these tickets to be available to your Client within a few minutes of placing the order. Only Ticket Groups with an expected_delivery_type of FILE_DOWNLOAD can be Instant Delivery. | |||||||||||||||||||||||||||||
public_notes | These notes should be displayed to the Client before purchasing and may include important details that may influence the buying decision. | |||||||||||||||||||||||||||||
featured | A boolean property used to indicate if a ticket group is considered to be “featured” based upon rules you provide. | |||||||||||||||||||||||||||||
wheelchair | A boolean property used to indicate if the tickets are marked as intended to be used by wheelchair or otherwise handicapped patrons. | |||||||||||||||||||||||||||||
view_type | One of: Full, Obstructed, Possibly Obstructed, or Partially Obstructed |
Properties not listed in the table above can be safely ignored.
Creating An Order
Once your customer has selected a ticket group to purchase you can move on to HOWTO: Create Orders Using The API.