---
title: Venue Seating Wizard documentation
description: The guests and tables CSV formats, group hierarchies and cohesion strength, seating preferences, locks, the objective function, and the export format.
canonical: https://venue-seating-wizard.aviramk.com/docs/
last-updated: 2026-08-23
---

# Venue Seating Wizard documentation

Everything you need to import a guest list, describe the constraints that matter, run the optimizer and export the result. The machine-readable version of this page is published at [/api/v1/csv-schema.json](https://venue-seating-wizard.aviramk.com/api/v1/csv-schema.json) and [/openapi.json](https://venue-seating-wizard.aviramk.com/openapi.json).

## Guests CSV

The guests file requires three columns — `name`, `party_size` and `groups`. Header matching is case-insensitive and surrounding whitespace is ignored. A row is one booking, not one person: `party_size` is how many chairs that entry needs, so a couple is a single row with a party size of two. A party size of zero marks the entry inactive. At most 1,000 guest rows and 10 MB are accepted.

```csv
name,party_size,groups
John Smith,2,Friends>College
Jane Doe,4,Family>Cousins
Bob Wilson,1,"Work,Friends"
Declined Guest,0,Family
```

## Groups and hierarchy

The `groups` cell is a comma-separated list of group paths, which is why a cell naming more than one group has to be quoted. A path uses `>` to nest a subgroup inside a parent — `Family>Cousins` places the guest in *Family* and in *Family > Cousins*. For right-to-left guest lists, `<` is accepted as the same separator. Groups are identified by their full path, so two different *Cousins* groups under different parents stay distinct. Each level is created with a default cohesion strength that rises with depth (3 at the top level, capped at 10), and every strength can be edited in the interface afterwards.

## Tables CSV

The tables file requires `id` and `capacity`, and optionally accepts `x` and `y` coordinates that place the table in the venue view. Capacity must be a positive integer. At most 100 tables are accepted.

```csv
id,capacity,x,y
T1,8,100,100
T2,10,200,100
Bar,4,,
```

## Seating preferences and locks

A seating preference points one guest at a target: a specific table, an area of the venue, or another guest. Preferences are soft — the optimizer pays a penalty proportional to how far the final placement lands from the requested target rather than refusing to seat anyone. A lock is hard: a locked guest stays on the table you chose and the optimizer rearranges everyone else around that decision.

## What the optimizer minimizes

The reported penalty is the sum of three terms, each scaled by 1000 and truncated to an integer so figures stay comparable between runs:

- **Group cohesion, weight 10** — `strength × √members` for every extra table a group is split across, with a credit back when a subgroup sits with its parent group.
- **Seating preferences, weight 1** — scaled by the guest's strongest group and by the normalized distance between the two tables, or from the table to the area rectangle.
- **Table usage, weight 0.5** — charged per table used, so the venue prefers fewer, fuller tables.

The search constructs a good arrangement greedily and improves it with simulated annealing over relocate, swap, ejection-chain and group-move neighbourhoods. Intermediate candidates may pass through over-capacity states under a penalty, because in a tightly packed venue the capacity-feasible neighbourhood can be disconnected — but only capacity-feasible arrangements are ever shown or exported.

## Export format

Exporting produces one row per table with the columns `Table,Guests,Taken,Capacity`.

```csv
Table,Guests,Taken,Capacity
T1,"John Smith, Jane Doe",2,8
T2,"Bob Wilson",1,10
```

## Try it with sample data

[https://venue-seating-wizard.aviramk.com/en/?demo=1](https://venue-seating-wizard.aviramk.com/en/?demo=1) opens the optimizer pre-loaded with the example guest list and table layout below, so you can watch a real optimization run before importing anything of your own. It seeds an empty workspace only, so it will not overwrite work in progress.

## Sample files and machine-readable schemas

- [/examples/guests.csv](https://venue-seating-wizard.aviramk.com/examples/guests.csv) — a valid guests file
- [/examples/guests-no-groups.csv](https://venue-seating-wizard.aviramk.com/examples/guests-no-groups.csv) — the same file without group data
- [/examples/tables.csv](https://venue-seating-wizard.aviramk.com/examples/tables.csv) — a valid tables file
- [/api/v1/csv-schema.json](https://venue-seating-wizard.aviramk.com/api/v1/csv-schema.json) — column-level schema for both files
- [/api/v1/objective.json](https://venue-seating-wizard.aviramk.com/api/v1/objective.json) — the objective function's terms and weights
- [/openapi.json](https://venue-seating-wizard.aviramk.com/openapi.json) — OpenAPI 3.1 description of the read-only API