Venue data

How we describe your venues, so a seat on your booking page finds its view. We set your venues up and keep them up to date; this page explains what we hold, what we need from you, and how to check a seat yourself. The record's full schema is VenueRecord in the API reference.

What a venue is

A venue is one auditorium or space: a main house and its studio are two venues. Each has an id such as ven_XXXXXXXXXXXXXXXX, belongs to one partner, and holds:

Your secret key can read your venue records (GET /manage/venues), and test them (below). Changes usually go through us: tell us what's changed, and we update the record.

Aliases: how your page finds its venue

Your page or script sends a context when it starts a session: the platform it's on and a venueRef, the name the platform uses for the venue. We look venueRef up among your venue's aliases, only ever within the venues your key may use. A venue id (ven_…) is also accepted as venueRef, on any platform.

There are two kinds of alias:

• Global aliases are unique across every partner, because older scripts send them without saying whose they are: legacyKey (the venue key an older Seat Preevue script sends, matched exactly, case and spaces included), legacyBaseUrl (an older script's imagery address) and origin (a booking site's address). We set these.
• Tenant-scoped aliases need only be unique within your own account, since platform ids repeat between platforms' customers: spektrixVenue, spektrixClient, tessituraVenue, criterionFacility, tixlyVenue, and other (a name you choose).

The alias types tried, in order, for each platform:

An alias can also pin an imagery set: one name for "the main house in cabaret layout", say. A venueRef that matches nothing is 404 venue_not_found; an alias another venue already holds is 409 alias_conflict (see Errors).

Layouts: which imagery set a performance gets

Many rooms have more than one layout (a cabaret night, a thrust stage, surtitles). Each layout is an imagery set of the same venue, so the same seat name can show a different view in each. For each session the set is chosen in this order:

1. context.imagerySet, if your page names a set;
2. the set an alias pins;
3. the seating plan's set (below);
4. the venue's layout rules;
5. otherwise default.

Layout rules decide from facts your platform knows, so a new layout is a change to your venue's data, never a script release. The ready-made scripts collect the facts their platform exposes: event attributes, sections, visible labels, zones, the seat map's mapId, and a productionId. A rule's conditions must all hold (an attribute equals a value; the sections include a list; labels or sections match a pattern; a zone; a map; a production), and the first rule that matches wins.

Some facts cost a request to collect, so they're asked for only when a rule needs them: the session answers layout: { status: "pending", needs: [...] } with the default set meanwhile, the script collects what's listed and extends the session, and the view switches if the answer changes. A fact the script couldn't get is reported as unavailable, and rules that need it are skipped.

Seating plans and area maps

Spektrix's new Seat Picker names seats by id rather than by name. For each seat it passes seatInfo, seven fields: venueId, planId, areaId, seatId, rowName, seatNo and seatName. The ids are 33 characters: digits, then A, then capital letters (1234AXXXX…).

Every seating plan has its own area and seat ids. A plan copied from another, even on the same venue, shares none with it. So a venue holds a map per plan under maps, keyed by the plan's planId:

"maps": {
  "1234AXXXX…": {
    "label": "Main house",
    "imagerySet": "default",
    "areaRefs": {
      "5678AXXXX…": { "section": "Stalls" },
      "9012AXXXX…": { "section": "Dress Circle" }
    },
    "seatRefs": {}
  }
}

• areaRefs turn each area id into the section (or area) name the seat-key rules use; the row and seat come from rowName and seatNo.
• seatRefs name the view for one particular seat id, for the odd seat the rules can't reach.
• The venue's own seatKey.areaRefs and seatKey.seatRefs are the fallback for every plan, tried after the plan's.
• The plan's imagerySet chooses the layout for performances on that plan.
• Up to 50 plans a venue. On a Spektrix venue, a plan or area id that isn't Spektrix-shaped is refused (400 validation_failed).
• Spektrix's ids are unique only within one Spektrix system, so spektrixVenue aliases are tenant-scoped and plan ids live only inside your venue's record: another partner's ids can never select your venue.

Seat keys

A seat key is the name of one seat's view within an imagery set, such as dress-circle-e-20. Your page sends what it knows about the seat as tokens (section, row, seat, area, label, suffix and others; on the Seat Picker, areaRef and seatRef as well), and the venue's seat-key rules turn them into a key:

1. A seatRef listed for the seat is tried first; an areaRef is looked up in the plan's map, then the venue's.
2. Each token is normalised (by default lowercased, with anything not a letter or digit becoming -), and characters such as a leading * can be trimmed.
3. Section names can be aliased (Grand Circle Boxes → boxes), and sections, rows, seats or whole keys remapped.
4. The venue's templates are tried in order, such as {section}-{row}-{seat}, then {row}-{seat}; a template whose tokens are missing is skipped.
5. The first candidate the set's manifest lists wins. No match means "no view for this seat", never a broken viewer.

SeatPreevue.resolveSeatKey(tokens) gives the same answer in a page (Quickstart: core).

Unmapped plans and areas: what visitors see

We're told about unmapped plans and areas each day, and map them. A new or copied seating plan is the usual cause, so tell us before it goes on sale. If a venue's button must stay visible meanwhile, we can switch page-start off for the venue: the button then shows on every seat, as with the Seat Picker's setting alone (Spektrix).

What to send us

• The page address of a seat-selection page on your live site, and any staging site, for each venue.
• The names your platform uses: the venue name or id, and on Spektrix's Seat Picker, one seatInfo from a seat in each area of each seating plan. In the browser's console on the seat map, the object the picker passes when "Check the view from seat" is clicked; copy it as it is.
• Example seats, as visitors see them (section or area, row, seat), including any odd ones: boxes, tables, restricted views, standing places.
• Layouts: which performances use which layout, and how your platform tells them apart (an event attribute, a seating plan, a section name).
• Changes ahead: a new seating plan, a copied plan, a new layout or a renamed area, before it goes on sale.

Never send keys, customer data or passwords. A seat's ids are fine: they name a seat, not a person.

Checking a mapping

With your secret key, POST /manage/venues/{venueId}/seat-keys/test runs a venue's layout and seat-key rules on up to 200 seats, without a session. Send the context your page would send and the seats as tokens, keys or named views (API reference):

curl -X POST "https://connect.seatpreevue.com/v1/manage/venues/ven_XXXXXXXXXXXXXXXX/seat-keys/test" \
  -H "Authorization: Bearer sk_live_…" -H "Content-Type: application/json" \
  -d '{
    "context": { "platform": "spektrix", "mapId": "1234AXXXX…" },
    "seats": [
      { "tokens": { "areaRef": "5678AXXXX…", "row": "E", "seat": "20" } },
      { "tokens": { "section": "Dress Circle", "row": "E", "seat": "20" } }
    ]
  }'

{
  "venueId": "ven_XXXXXXXXXXXXXXXX",
  "imagerySet": "default",
  "layout": { "status": "resolved" },
  "manifest": true,
  "results": [
    { "matched": true, "key": "stalls-e-20", "candidates": ["stalls-e-20", "e-20"] },
    { "matched": true, "key": "dress-circle-e-20", "candidates": ["dress-circle-e-20", "e-20"] }
  ]
}

Reading the answer:

• imagerySet is the layout the context chose; layout.needs lists facts a rule is waiting for.
• matched: true with a key: the seat has a view.
• matched: false: no candidate is in the set. candidates shows every key tried, so a naming difference is easy to spot: send us the seat and what you expected.
• matched: false with no candidates for a seat sent with an areaRef: the area id isn't in the plan's map or the venue's (an unmapped area). Send us a seatInfo from that area.
• manifest: false: the set has no list of seats yet, so nothing is matched.

The same check runs when we set a venue up, against the example seats you send.