Seat data

There are typically two types of seating information that a client needs:

• The actual layout of the seats in a session including the area categories and the individual seats therein. This is used to render a seat map in a UI.
• The current status of the sesssion in terms of seat availability, from high-level seats remaining data on a session to the low-level sold status of individual seats

The Connect API provides this information though a mix of APIs which are described below.

OData session data

A session returns a number of seating-related properties.

Important Note:

This data, especially SeatsAvailable data is NOT real-time data and may be out of date to varying degrees based on the back-end configuration and caching configuration of Connect.

{
    "ID": "0000000001-51592",
    "CinemaId": "0000000001",
    "SessionId": "51592",
    "AreaCategoryCodes": [
        "0000000001",
        "0000000002"
    ],
    "Showtime": "2019-05-03T18:00:00",
    "IsAllocatedSeating": true,
    "SeatsAvailable": 251,
    "ScreenName": "ABC Screen 1",
    "ScreenNumber": 1,
    "SoldoutStatus": 0,
}

Seat plan data

There are several ways of retrieving seat-plan data based on the specific client needs. Each returns essentially the same information but the subleties in their behaviour are worth understanding.

Important Note

The sophistication of the seat plan has evolved over the years and these APIs can be quite granular. It is important for modern clients to follow the best-practice in requesting seat plans:

• If available, specify the structured SeatDataFormat (examples below). The alternative is a legacy encoded string and not specifying either will return both resulting in a performance hit on the server.
• If available, include all the Include*** properties. These exist for certain compatibility reasons and all modern clients should deal with all data potentially configurable in a seat layout

Structured seat layout data

The following is an example of the a seat plan/layout data. It consists of a mix of:

• The physical seat layout (areas, rows, seats)
• Physical dimensions that can be used for drawing seat map UI*
• The SeatStyle of the individual seats (e.g. normal, sofa, wheelchair etc.)
• The Status of the individual seats (e.g. sold, reserved etc.)

Please review the API reference documentation for SeatLayoutData specifics.

{
	"SeatLayoutData": {
		"Areas": [
			{
				"Number": 1,
				"AreaCategoryCode": "0000000001",
				"Description": "Stalls",
				"DescriptionAlt": "",
				"NumberOfSeats": 2,
				"IsAllocatedSeating": true,
				"Left": 0.2,
				"Top": 29.33,
				"Height": 18.83,
				"Width": 99.8,
				"Rows": [
					{
						"PhysicalName": "A",
						"Seats": [
							{
								"Position": {
									"AreaNumber": 1,
									"RowIndex": 0,
									"ColumnIndex": 1
								},
								"Priority": 2,
								"Id": "1",
								"Status": 0,
								"SeatStyle": 1,
								"OriginalStatus": 0
							},
							{
								"Position": {
									"AreaNumber": 2,
									"RowIndex": 0,
									"ColumnIndex": 3
								},
								"Priority": 2,
								"Id": "2",
								"Status": 0,
								"SeatStyle": 1,
								"OriginalStatus": 0
							}
						]
					}
				],
				"RowCount": 1,
				"ColumnCount": 2
			}
		],
		"AreaCategories": [
			{
				"AreaCategoryCode": "0000000001",
				"SeatsToAllocate": 0,
				"SeatsAllocatedCount": 0,
				"SeatsNotAllocatedCount": 0,
				"SelectedSeats": [],
				"IsInSeatDeliveryEnabled": false
			}
		],
		"BoundaryRight": 100,
		"BoundaryLeft": 0,
		"BoundaryTop": 29.33,
		"ScreenStart": 0,
		"ScreenWidth": 100
	},
	"ResponseCode": 0,
	"ErrorDescription": null
}

GetSessionSeatPlan

This endpoint is unrelated to any order and can be used to display the current status of a session in map form or more commonly for seat-first style ticketing UIs where the customer must first select seats in a seat map before selecting their tickets

Important Note:

This endpoint (due to including current seat statuses) retrieves its data from the cinema and such adds load to both Connect and downstream applications at cinema. It is also an endpoint that is typically under high load. As such most instances of Connect will have a certain level of short-term caching behind the data. As such it cannot be considered real-time but should be close-to-real-time and more up-to-date than the session data.

GET: /restdata.svc/cinemas//sessions//seat-plan

Response:

{
	"SeatLayoutData": {},
	"ResponseCode": 0,
	"ErrorDescription": null
}

GetSessionSeatData

This end-point returns the same response as GetSessionSeatPlan but is designed specifically for ticket-first seating scenarios where a customer has already selected tickets.

• This endpoint has NO caching and CAN be considered real-time as it gets the data directly from the cinema each time.
• This endpoint has a number of options for excluding certain seat properties as well as an option to return the order along-side the seat plan
• The SeatDataFormat is a key property and should always be set to 2 (structured)
• This endpoint, since it is related to a specific order will return the seats assigned to the current order with the status of reserved, whereas they would be flagged as available in GetSessionSeatPlan
• This endpoint will fail if no tickets have been added to the order

POST: /restticketing.svc/order/seats/get

Request:

{
  "CinemaId": "{{cinemaId}}",
  "SessionId": "{{sessionId}}",
  "UserSessionId": "{{userSessionId}}",
  "ReturnOrder": true,
  "ExcludeAreasWithoutTickets": false,
  "IncludeBrokenSeats": true,
  "IncludeHouseSpecialSeats": true,
  "IncludeGreyAndSofaSeats": true,
  "IncludeAllSeatPriorities": true,
  "IncludeSeatNumbers": true,
  "IncludeCompanionSeats": true,
  "SeatDataFormat": true
}

Response:

{
	"Result": 0,
	"Order": {},
	"SeatLayoutData": {},
	"SeatsNotAllocated": false,
	"ErrorDescription": null
}

AddTickets response

The AddTickets endpoint has an ReturnSeatData property as well as related properties similar to GetSessionSeatData. Specifying this will return the same seat layout data as that endpoint.