Skip to main content
GET
/
events
/
{id}
/
seatmap
Get Event Seatmap
curl --request GET \
  --url http://localhost:50001/events/{id}/seatmap
{
  "eventId": "<string>",
  "eventName": "<string>",
  "eventDescription": "<string>",
  "eventDate": "<string>",
  "basePrice": 123,
  "seats": [
    {
      "id": "<string>",
      "sectionCode": "<string>",
      "rowNumber": 123,
      "seatNumber": 123,
      "price": 123,
      "status": "<string>"
    }
  ]
}

Overview

This endpoint returns detailed information about a specific event along with its complete seatmap, including all seats with their availability status, pricing, and location details. This is the primary endpoint for displaying seat selection interfaces to users. Use this endpoint when you need to:
  • Display an interactive seat map to users
  • Show real-time seat availability
  • Allow users to select seats for purchase

Authentication

No authentication required. This is a public endpoint.

Path Parameters

id
string
required
The unique identifier (UUID) of the event to retrieve with seatmap.Example: 550e8400-e29b-41d4-a716-446655440000

Response

eventId
string
required
Unique identifier for the event (UUID format)
eventName
string
required
Name of the event
eventDescription
string
required
Detailed description of the event
eventDate
string
required
Date and time of the event (ISO 8601 format in UTC)
basePrice
number
required
Base price for tickets to this event
seats
array
required
Array of all seats for this event

Example Request

curl -X GET http://localhost:50001/events/550e8400-e29b-41d4-a716-446655440000/seatmap \
  -H "Content-Type: application/json"

Example Response

200 OK
{
  "eventId": "550e8400-e29b-41d4-a716-446655440000",
  "eventName": "Coldplay - Live in Santiago",
  "eventDescription": "World tour 2026",
  "eventDate": "2026-03-15T19:00:00Z",
  "basePrice": 50.00,
  "seats": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "sectionCode": "A",
      "rowNumber": 1,
      "seatNumber": 1,
      "price": 50.00,
      "status": "available"
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440002",
      "sectionCode": "A",
      "rowNumber": 1,
      "seatNumber": 2,
      "price": 50.00,
      "status": "available"
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440003",
      "sectionCode": "A",
      "rowNumber": 1,
      "seatNumber": 3,
      "price": 50.00,
      "status": "reserved"
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440004",
      "sectionCode": "VIP",
      "rowNumber": 1,
      "seatNumber": 1,
      "price": 150.00,
      "status": "sold"
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440005",
      "sectionCode": "VIP",
      "rowNumber": 1,
      "seatNumber": 2,
      "price": 150.00,
      "status": "available"
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440006",
      "sectionCode": "B",
      "rowNumber": 5,
      "seatNumber": 10,
      "price": 35.00,
      "status": "available"
    }
  ]
}

Error Responses

The event with the specified ID does not exist in the system.The endpoint returns HTTP 404 with no response body when the event is not found.
The provided event ID is not in a valid UUID format.
{
  "error": "Invalid event ID format",
  "message": "The event ID must be a valid UUID"
}
Server encountered an unexpected error while processing the request.
{
  "error": "Internal server error",
  "message": "An unexpected error occurred while fetching the event seatmap"
}

Seat Status Reference

StatusDescriptionUser Action
availableSeat is available for reservationUser can select and reserve this seat
reservedSeat is temporarily reserved by another userSeat cannot be selected (reservation expires in 30 minutes)
soldSeat has been purchasedSeat is no longer available

Integration Flow

This endpoint is typically used as the first step in the ticket purchase flow:
  1. GET /events//seatmap - Display available seats to the user
  2. User selects an available seat
  3. POST /reservations (Inventory service) - Reserve the selected seat
  4. Wait 2-3 seconds for reservation event to propagate via Kafka
  5. POST /cart/add (Ordering service) - Add reserved seat to cart
  6. POST /orders/checkout (Ordering service) - Complete the purchase
See the Frontend Integration Guide for a complete end-to-end example.

Notes

  • All prices are in USD
  • Event dates are returned in UTC timezone (ISO 8601 format)
  • Seat status is updated in real-time based on reservations and purchases
  • Reserved seats automatically expire after 30 minutes if not added to cart
  • The id parameter must be a valid UUID (GUID) format
  • Seats are ordered by section, row, and seat number in the response
  • Individual seat prices may differ from the base price depending on section (e.g., VIP seats)

Performance Considerations

  • This endpoint may return large payloads for events with many seats
  • Consider implementing pagination or filtering on the client side for large venues
  • The response is cacheable for short periods (e.g., 5-10 seconds) to reduce server load
  • Seat status should be refreshed periodically to show real-time availability

Build docs developers (and LLMs) love