Reference data overview

The reference data endpoints in the Connect API provide read-only access to all the data you need to provide effective and feature rich applications. This section provides a basic overview on what the key reference data entities are.

Key reference data entities

Cinema

The cinema entity (also referred to as site) represents a physical cinema location, and is generally the first entity a customer deals with in making a purchase. The cinema entity has a key related entity in sitegroup which can be used to group cinemas to simplify a customer's experience on large circuits.

Cinema operator

The cinema operator entity commonly represents a film exhibitor, but potentially represents any entity whose revenue is tracked separately at a cinema e.g. a bar or restaurant

Film

The film entitiy provides full details of a film (such as synopsis, and cast and crew details), and is useful for providing rich, user interface experiences. It has related entities of filmperson and filmgenre.

ScheduledFilm

A scheduledfilm represents an instance of a film as scheduled at a site. While containing less information than the film entity, it is generally more useful and often more appropriate to use as it contains film information specific to a cinema and its location, including:

• Whether or not the film is showing at the cinema
• What the film is called at the cinema location (potentially in the primary language of the cinema's region)
• Local cut running time, distributor etc.

This information may or may not vary per cinema depending on the nature of the circuit. However, full support is available if needed.

Session

The sessions (or showtimes) of a circuit are a key entity as they are an essential part of the ticket selling process. As well as telling customers when a film is showing, a session contains numerous other properties important to their experience including custom attributes, screen/seating information, and ticket selling restrictions.

SessionTicket

Each session has its own set of tickets available as sessionticket entities. Depending on the pricing configuration of the circuit, these may vary a lot or not at all. Common variations of ticket availability are due to prices fluctuating based on time of day, day of week or screen experience.

SeatPlan

The seat plan describes the physical cinema auditorium in terms of seat layout. It can include the sold/unsold status of each seat.

Attribute

Attributes are a powerful part of Vista configuration and can be used in many ways. Essentially a way of tagging key entities with additional custom properties, attributes can be applied to both Films and Sessions. Common examples would be to indicate certain experiences such as closed-caption or 3D sessions. Understanding how the circuit uses attributes is key to providing appropriate information to customers during ticket purchase.

Concession

The concession item represents any non-ticket purchasable item in Vista. Common examples include food and beverage concessions but can include anything from loyalty rewards and full-on menu items to gift cards, vouchers and merchandise.

OData

Much of the reference data API in Connect makes use of the OData conventions V2. Details of these can be found at www.odata.org/documentation/odata-version-2-0/uri-conventions/.

OData allows clients to select subsets of data to return saving bandwidth as well as some basic filtering logic. Connect also has certain limited support for the expansion of linked entities. For more examples see the example queries.

Accessing the data

How often a client application fetches data form Connect may determine what APIs are used. There are typically two styles of Connect clients.

• Real-time client - Clients of this type drive user interfaces directly off the Connect API and as such are after fast, efficient data calls that respond to user actions. Clients include standard cinema ticketing web-sites and mobile apps.
• Batch client - Clients of this type load data from Connect into their own store/cache, which in turn provides real-time services to their applications. Clients include systems in which the owners want more control over the APIs their client applications access, or aggregators that may be serving data from multiple sources in addition to Connect.

Basic real-time client call flow

The following describes a basic call flow for a real-time interaction driven directly by customer actions:

• V1.OData.Cinemas
  • Get list of cinemas for the customer to select
• V1.OData.GetNowShowingScheduledFilms
  • Gets a list of films showing for cinema(s)
  • Can filter by cinema(s), sitegroup, or even attribute
  • Can expand to return sessions as well
• V1.Data.GetTicketsForSession
  • Gets tickets for a session selected by the customer
• V1.Data.GetSessionSeatPlan
  • Gets the seat plan and available seats for the selected session
• V1.Data.GetConcessionItems
  • Gets the concession items available to sell alongside tickets

Basic batch client call flow

The following describes a basic background polling/synchronisation system between an external system and Connect:

• V1.OData.Cinemas
  • Gets a list of cinemas to load data for
• V1.OData.Films
  • Gets a list of film entities for local system/cache
• V2.BatchData.GetBatchDataForCinema
  • Gets scheduledfilms, sessions and tickets for a single cinema in a single call

Note: Seat plans are not included in batch data as this data is considered too 'real-time' to be returned in a batched manner.