The ideal catalog API has four basic components
- venue
- lineup
- category
- event
Each physical venue sholud be a single record in your api. Each venue should have an id, which should ideally be an integer. The following metadata is required
- id
- name
- location (typically latitutde/longitude)
things which are logical and nice to have
- timezone
- address / city / state / postalcode / country
- phone number
things which are bonus and can be rendered when present
- venue url
- capacity
- image assets
A category is a type of event / performer. They can have varying degrees of specificity, and can sometimes be logically nested. For example, "MLB" and "Baseball" are both categories on seatgeek, and any semantics that apply to baseball apply by assumption to MLB (for example, the requirement that two teams be participating in any baseball event). Other categories can be more vague and subject to interpretation, for example a "Cirque du Soleil" could be in a category called "Theater", a category called "Las Vegas Shows", or a category called "Circus". Much depends on how your system handles categories.
Regardless of how categories are subdivided, the following base constraints should be met to interoperate with seatgeek
- sports / concerts (which includes music festivals) / theater (which includes symphony orchestras and opera) are our 3 top level categories
- major professional sports and college sports (NFL, NBA, NHL, MLS, NBA, NCAA FB, and NCAA BB) are categorized separately
- music genres are ignored by seatgeek, but are nice to have
At seatgeek, we represent category data as a list as follows
"taxonomies": [
{
"parent_id": null,
"id": 1000000,
"name": "sports"
},
{
"parent_id": 1000000,
"id": 1010000,
"name": "baseball"
},
{
"parent_id": 1010000,
"id": 1010100,
"name": "mlb"
}
],
the logical nesting is represented explicitly. This is optional but not strictly necessary; as long as we can create a mapping from category_id to seatgeek_category_id, we can integrate your catalog.
A performer is anything for which it is logical to create a schedule. A performer is a catch-all term which we use to encompass
- teams [New York Mets]
- headlining athletes [Floyd Mayweather]
- auto races [Daytona 500]
- tournaments [NCAA Tournament, The Masters]
- recurring events [The Rose Bowl]
- bands / musicians [Billy Joel, U2]
- broadway shows [Book of Mormon]
- musical ensembles [New York Philharmonic]
- dances companies [American Ballet Company]
Performers typically have a category associated with them e.g. "MLB" for the mets above.
The following metadata is required
- id
- name
An event (can think of this as a "performance") is defined by
- The venue at which it occurs
- The exact date and time at which it occurs
- The lineup of performers participating in the event
** all events must have a non-empty lineup **. In addition, one performer must be designated as the "primary" performer, which is a concept that encompasses
- home team [for team sports]
- tournament name [for tournament events]
- recurring event name [for recurring events like "The Rose Bowl"]
- headliner [in the context of a concert]
- music festival name [in the context of a music festival]
- show name [for theater]
Required metadata
- id
- title
- venue_id [the venue at which the event occurs, designated by its id]
- datetime [in UTC preferably, the start date/time of the event]
- lineup [list of performer ids , including one which is designated as primary somehow]
- category [designated by id]
The second critical piece of an integartion is to build a feed of current inventory.
Requirements
- the feed must accept an event ID and return a completely list of all inventory in a single response
- the feed must be as up-to-date as possible
- some caching is acceptable, but should be minimized
Required Fields
- id [unique system side]
- section
- row
- seat number range
- quantity
- allowed splits [see below]
- price per ticket
- fees
- shipping methods with associated fees
- seller notes
Note: The listing api should have the ability to accept a single listing_id and return information about just that listing.
There are several ways to deliniate shipping methods, and the details will vary on your system. The basic requirement is that for each SEAT or LISTING, depending on which style API you've implemented, we must be able to identify all available shipping methods and their associated per transaction fees.
one way to do this is to have the details in line with the listing
listings: [
{
id: 1,
section: 101,
...
shipping_options: [
{
"method_name" : "Email",
"fee" : 0
},
{
"method_name" : "FedEx",
"fee" : 5
}
],
}
]
another is to put all shipping info in a request subdocument and refer to them via ids
shipping_methods: {
1: {
"method_name" : "Email",
"fee" : 0,
"id" : 1,
}
2: {
"method_name" : "FedEx",
"fee" : 5,
"id" : 2,
}
}
listings: [
{
id: 1,
section: 101,
shipping_options: [1, 2]
}
]
either of these is acceptable.
INSTANT DELIVERY: SeatGeek defines instant delivery as a ticket that can be delivered to a user within 30 seconds, and which does not require a step of human approval to authorize the transaction.
ETICKET: SeatGeek defines an eticket as a ticket that can be emailed to a user in a PDF format, or delivered electronically to their mobile device.
SPLITS: A split is an allowed partial order on a listing. FOr example, if a listing has 4 tickets, seats 1-4, the seller will commonly declare that a customer could by a lot of 1, 2, or 4 seats in an order, but not 3 seats (so as to avoid being left with an unsold single seat). In the API, splits should be designed as a list of integers reflecting allowed lot sizes. For example
{
id: 1,
section: 101,
row: 1,
quantity: 4,
splits: [1,2,4],
price: 50
...
}