Availability specification

  • The Availability message indicates whether a ticket is available or unavailable, using the available or unavailable fields respectively.

  • The Available message specifies the number of remaining seats (available_seat_count), the total number of seats (total_seat_count), and an estimate of availability using the AvailabilityEstimate enum.

  • The AvailabilityEstimate enum in the Available message provides relative availability indicators, such as MANY_SEATS_AVAILABLE, HALF_OF_SEATS_AVAILABLE, and VERY_FEW_SEATS_AVAILABLE.

  • The Unavailable message details the reason for unavailability, using the Reason enum which includes options such as BOOKED, CANCELED, and TEMPORARILY_UNAVAILABLE.

  • Partners can provide exact numbers, relative estimates, or just an indication that at least one seat is available in the Available message.

Proto Definition

message Availability {
  oneof availability_status {
    // The ticket is available.
    Available available = 1;

    // The ticket is unavailable.
    Unavailable unavailable = 2;
  }
}

// Message representing how many seats are still available in the specified
// service class.
// Partners can:
// - provide exact numbers for available, and optionally total seats
// - provide a relative availability estimate
// - leave the message empty, if all they only know is that at least one seat is
//   still available
message Available {
  // The number of remaining seats.
  // This is optional. You can pass an empty Available message to just indicate
  // that at least one seat is available.
  int32 available_seat_count = 1;

  // The total number of seats.
  int32 total_seat_count = 2;

  // An estimate for the relative number of available seats.
  enum AvailabilityEstimate {
    // > 70% of total seats are still available
    MANY_SEATS_AVAILABLE = 1;

    // 30-70% of total seats are still available
    HALF_OF_SEATS_AVAILABLE = 2;

    // 10-30% of total seats are still available
    FAIR_NUMBER_OF_SEATS_AVAILABLE = 3;

    // 5 - 10% of total seats are still available
    FEW_SEATS_AVAILABLE = 4;

    // < 5% of seats are still available
    VERY_FEW_SEATS_AVAILABLE = 5;
  }

  AvailabilityEstimate availability_estimate = 3;
}

message Unavailable {
  // Different reasons why a ticket could be unavailable.
  enum Reason {
    // All tickets in this ServiceClass have been booked.
    BOOKED = 1;

    // This particular service (e.g. train) was extraordinarily canceled.
    // Permanent service changes should be communicated via GTFS.
    CANCELED = 2;

    // The trip cannot be priced nor sold at the moment.
    TEMPORARILY_UNAVAILABLE = 3;
  }

  Reason reason = 1;
}

JSON Sample

{
  "available": {
    "available_seat_count": 10,
    "total_seat_count": 200
  }
}