Seat Map

Seat maps let passengers choose a specific seat for their journey. When support by the carrier, you can show the vehicle layout in your UI and let users pick from the seats that are still free right before checkout.

This documentation outlines the integration flow for rendering visual seat maps and booking specific seats. To maximize performance and reduce latency, this API explicitly separates the physical shape of a vehicle from the real-time status of its seats.

Splitting Static Layouts and Dynamic Availability

Seat selection is split into two endpoints on purpose: one endpoint provides the live availability layer, and the other provides the layout structure. The availability response answers booking questions such as which seats are selectable, whether a seat is preselected, whether it is available as an add-on, and which seat_id must be sent later in /reservations/create. The /layouts endpoint, by contrast, is only about the visual map of the vehicle or deck: how seats are positioned and how the seat map should be rendered.

This separation keeps the integration lighter and more flexible: the layout can be treated as a reusable visual template, while availability remains the real-time booking source of truth. In practice, retailers use the availability response to know what can be sold, and the layout response to decide how to display it.

To help visualize how such a layout renderer could be built, AI tools such as Gemini or ChatGPT can also be useful for quickly prototyping seat-map UI concepts or frontend structures.

Building Your Cache of Layouts

The /layouts endpoint returns the detailed physical definition of vehicle decks. It allows retailers to cache the visual geometry (walls, seats, amenities) and render it independently of real-time availability.

To build your layout cache proactively, you can request all layouts for a specific carrier at once.

 
https://api.demo.distribusion.com/retailers/v4/layouts?marketing_carrier=IQCB

Then during the seat reservation flow you should use the /seats/availability response to identify the layout_id reference and check whether you already have that layout cached locally. If not, you should call the layouts endpoint once, store the returned structure in your cache keyed by the layout identifier, and then reuse it for future requests that reference the same layout. This keeps the integration efficient, because the layout can be treated as a reusable template while availability remains the real-time source of truth for what can actually be sold.

Checking Seat Availability

The endpoint /seats/availability returns the dynamic inventory data for a specific offer_id. When booking a return trip or a multi bound trip, you can include multiple offer_id to the request.

Sample Request

 
https://api.demo.distribusion.com/retailers/v4/seats/availability?offers[][id]=180a4e81-6450-44a5-b6a4-338e650d8ec2%7C2&offers[][id]=8b9f97fc-777e-4aff-91d4-f47d8ff18f9b%7C0

Response Structure

The availability response is deeply nested to represent the physical layout of the journey:

• Connections: A list of connections (bounds) associated with the requested journey.
• Segments: The list of legs that make up this connection.
  • Vehicles: The physical transport units for this segment.
    • Coaches: The list of distinct carriages making up the vehicle.
      • Decks: The vertical levels within this coach. Contains the layout_id to reference the static layout of this deck.
        • Compartments: Logical groupings of inventory within the deck.
          • Seats: The list of individual seat inventory items available in this compartment. Includes seat_code to match against the layout, and overall_availability_status.

Fetching Layouts

In case a layout does not exist in your cache you can call the /layouts endpoint with the specific layout_id.

Request Sample

 
https://api.demo.distribusion.com/layouts?marketing_carrier=IQCB&ids[]=1cd51737-c6d5-4596-a656-1ac7fdcdab8b

Response Structure

• id: The layout identifier for this specific physical configuration.
• size: Defines the bounding box of the layout grid (length, width).
• elements: Static visual structures and signage (Seats, Walls, Doors, Stairs, Amenities, Travel class, etc.) that form the background map. Elements have 2 types: place (bookeable accommodations) and graphic_element. Both share a visual_position object containing the {x, y, z} coordinates on the layout grid.

Creating a Reservation with Seats

The seat can be provided by the main standalone offer (because seat selection is free, does not incur in a fee), or it could come with a fee as an addon offer.

Inside the corresponding offer, indicate as many seat_selections as necessary. For each, the segment_id, passenger_id and seat_id is needed.

Example A: Seats included on the main offer

The seats are included as part of the main offer, so there is no additional offer in the array. Seat selection is indicated as part of the main offer.

 
{
  "locale": "en",
  "retailer_partner_number": "123456",
  "email": "john.smith@email.com",
  "passengers": [
    {
      "id": "pax-33-1",
      "type": "PNOS"
    },
    {
      "id": "pax-33-2",
      "type": "PNOS"
    }
  ],
  "offers": [
    {
      "id": "dab3d49f-e79d-4c6b-a780-6f37a0cd854a|2",
      "passenger_ids": [
        "pax-33-1",
        "pax-33-2"
      ],
      "seat_selections": [
        {
          "segment_id": "IQCB-DEBERCBS-DEDRSBSA-2026-10-09T13:00-2026-10-09T15:00-0",
          "passenger_id": "pax-33-1",
          "seat_id": "v1|IQCB|19e2627b0d047489|0|0|0|coach-0-0-0|coach-0-0-0-deck-0|E5|f7bae2273c449e5e8202b6216cec02fe4120dd81a33c8bafb709f4d24297023c"
        },
        {
          "segment_id": "IQCB-DEBERCBS-DEDRSBSA-2026-10-09T13:00-2026-10-09T15:00-0",
          "passenger_id": "pax-33-2",
          "seat_id": "v1|IQCB|19e2627b0d047489|0|0|0|coach-0-0-0|coach-0-0-0-deck-0|E6|a4cbd1183c449e5e8202b6216cec02fe4120dd81a33c8bafb709f4d24297023d"
        }
      ]
    }
  ]
}

Example B: Add-on seats to the main offer

The customers have chosen more expensive seats. Each chosen seat references an add-on offer in /seats/availability response. Hence, each seat selection is indicated under its corresponding add-on offer. If both passengers chose seats that reference the same addon offer ID, both selections are grouped under one offer entry. If selected seats reference different offer IDs, each would appear under its own offer entry. In total, for this sample request below for two passengers there are two offer_id values indicated: one for the main admission offer and one for the seat add-on offer covering both selections.

 
{
  "locale": "en",
  "retailer_partner_number": "123456",
  "email": "john.smith@email.com",
  "passengers": [
    {
      "id": "pax-33-1",
      "type": "PNOS"
    },
    {
      "id": "pax-33-2",
      "type": "PNOS"
    }
  ],
  "offers": [
    {
      "id": "dab3d49f-e79d-4c6b-a780-6f37a0cd854a|2"
    },
    {
      "id": "800e3599-ece4-40bb-a9e3-937f4253b7c0",
      "passenger_ids": [
        "pax-33-1", "pax-33-2"
      ],
      "seat_selections": [
        {
          "segment_id": "IQCB-DEBERCBS-DEDRSBSA-2026-10-09T13:00-2026-10-09T15:00-0",
          "passenger_id": "pax-33-1",
          "seat_id": "v1|IQCB|19e2627b0d047489|0|0|0|coach-0-0-0|coach-0-0-0-deck-0|E5|f7bae2273c449e5e8202b6216cec02fe4120dd81a33c8bafb709f4d24297023c"
        },
        {
          "segment_id": "IQCB-DEBERCBS-DEDRSBSA-2026-10-09T13:00-2026-10-09T15:00-0",
          "passenger_id": "pax-33-2",
          "seat_id": "v1|IQCB|19e2627b0d047489|0|0|0|coach-0-0-0|coach-0-0-0-deck-0|E6|a4cbd1183c449e5e8202b6216cec02fe4120dd81a33c8bafb709f4d24297023d"
        }
      ]
    }
  ]
}

API Workflow

The seat booking process consists of 5 main steps that should be completed for carriers that support seat map reservation. We recommend starting this flow after your /connections/vacancy request.

1. Fetch Live Seat Availability: Triggered when a user selects a journey or a specific offer, you request /seats/availability. This returns real-time statuses, pricing, eligibility per passenger, and the specific layout_ids to display.
2. Resolve the Visual Map: Your system checks if it has the detailed layout for that layout_id cached or stored locally.
   1. Hit: Retrieve the map instantly from your cache.
   2. Miss: Call /layouts with the specific layout_id to fetch the definition and store it for future requests. Because layout IDs are immutable, you can cache them aggressively without fear of data staleness.
3. Render & Merge: Your application draws the visual map using the layout data (walls, seats, tables) and overlays the live inventory using the availability data by matching them via the unique seat_code.
4. Create reservation: You send a /reservations/create request with passengers and offers (and seat selections placed in the appropriate offer object).
5. Confirm / Check status: Follow the normal reservation confirmation flow (confirm, then poll/check booking status).