Bus Booking

Manage and retrieve ticket information.

Endpoints

Search Bus Offers

Search for available bus trips between two locations on a specific date.

Endpoint: GET /api/trip/search

Example Request:

GET /api/trip/search?from=LUSAKA:RGN:0&to=JOHANNESBURG:RGN:0&date=2025-12-31

Query Parameters

Parameter	Type	Required	Description
from	string	Yes	Origin stop ID in the format CITY:RGN:0 (e.g., LUSAKA:RGN:0)
to	string	Yes	Destination stop ID in the format CITY:RGN:0 (e.g., JOHANNESBURG:RGN:0)
date	string	Yes	Travel date in YYYY-MM-DD format (e.g., 2025-12-31)

Response Structure

The response contains two main objects:

Field	Type	Description
exactRoute	object	Direct routes matching the origin and destination
alternatives	object	Alternative routes or connections (if no direct routes are found)

Exact Route Object

The exactRoute object is keyed by route name (e.g., "Lusaka - Johannesburg") and contains an array of available trips.

Trip/Offer Fields

Field	Type	Description
id	string	Unique trip/frequency identifier
companyId	string	Bus company MongoDB ID
companyName	string	Official company name
companyTradingName	string	Trading name of the company
companyLogo	array	Array of logo objects with type, name (TICKET/DARK/LIGHT), base64, and url
tinNumber	string	Company tax identification number
frequencyId	string	Unique identifier for the trip frequency
tripsId	string	Internal trip identifier (format: ROUTE:DIRECTION)
routeId	string	Route identifier
routeName	string	Human-readable route name
routeShortName	string	Abbreviated route name (e.g., LSK - JHB)
routeColor	string	Hex color code for route display
routeTextColor	string	Hex color code for text on route color
origin	string	Origin city name
destination	string	Destination city name
headsign	string	Full route description with intermediate stops
price	number	Base ticket price in local currency
priceCurrency	string	Currency code for prices (e.g., ZMW)
departureDate	string	Departure date in ISO 8601 format
departureTime	string	Departure time in HH:mm format
reportingTime	string	Recommended arrival time at station (before departure)
travelTime	string	Formatted travel duration
estimatedTravel	object	Detailed travel time with hours, minutes, formatted, and formattedLong
estimatedArrivalTime	string	Expected arrival time at destination
estimatedArrivalDate	string	Expected arrival date in ISO 8601 format
estimatedArrivalDays	number	Number of days after departure for arrival (0 = same day, 1 = next day, etc.)
timezone	string	Timezone for departure (e.g., Africa/Lusaka)
direction	string	Trip direction: OUTBOUND or INBOUND
hasLeftOrigin	boolean	Whether the bus has already departed
canceled	boolean	Whether the trip is canceled
availableSeats	number	Number of seats still available
agentCommission	number	Commission amount for booking agents

Important Information Array

Field	Type	Description
custom	boolean	Whether this is a custom message
icon	string	Icon identifier (e.g., passport)
iconType	string	Icon type classification
code	string	Information code (e.g., ID_REQUIRED)
values	array	Additional values for dynamic messages

Stop Times Array

Each stop in the route is represented as:

Field	Type	Description
stopId	string	Unique stop identifier
stopName	string	Stop/city name
stopDescription	string	Full address/description
stopSequence	number	Order in the route (0 = first stop)
arrivalTime	string	Arrival time at this stop
departingTime	string	Departure time from this stop
latitude	number	Stop GPS latitude
longitude	number	Stop GPS longitude
estimatedArrivalDate	string	Expected arrival date at this stop
estimatedDepartureDate	string	Expected departure date from this stop
estimatedArrivalDays	number	Days from trip start to arrival at this stop
estimatedDepartureDays	number	Days from trip start to departure from stop
stop_timezone	string	Timezone of the stop
city_geohash	string	Geohash for location-based queries
popularity	number	Stop popularity score

Vehicle Object

Field	Type	Description
id	string	Vehicle MongoDB ID
plateNumber	string	Vehicle registration plate
type	string	Vehicle type (e.g., BUS)
vehicleClass	string	Class: LUXURY, SEMI_LUXURY, or ORDINARY
seats	number	Total seat capacity
seatingColumns	number	Number of seat columns
numberOfDoors	number	Number of doors
steeringWheelPosition	string	LEFT or RIGHT
amenities	array	Available amenities (e.g., ["AC", "TV"])
seatingGrid	object	Detailed seat layout by section

Seating Grid

The seatingGrid contains sections keyed by unique identifiers. Each section includes:

Field	Type	Description
sectionName	string	Section class (e.g., ORDINARY)
seatingRows	string	Number of rows
seatingColumns	string	Number of columns
seats	string	Total seats in section
seatsReserved	number	Number of reserved seats
seatsAvailable	number	Number of available seats
seatingGrid	array	Array of seat objects

Each seat object in the grid:

Field	Type	Description
id	string	Unique seat identifier
label	string	Seat number label displayed to passengers
positionX	number	Column position (0-indexed)
positionY	number	Row position (0-indexed)
key	string	Grid key (usually same as id)
type	string	SEAT, AISLE, DOOR, or DRIVER
class	string	Seat class: LUXURY, SEMI_LUXURY, or ORDINARY
orientation	string	Seat orientation (e.g., UP)
available	boolean	Whether the seat is available for booking

Fare Rules Array

Each fare rule defines pricing between specific stops:

Field	Type	Description
id	string	Unique fare rule identifier
originId	string	Origin stop ID
destinationId	string	Destination stop ID
originCity	string	Origin city/region name
destinationCity	string	Destination city/region name
baseCurrency	string	Base currency code
prices	object	Prices by class (LUXURY, SEMI_LUXURY, ORDINARY, agentCommission)
otherCurrencies	object	Converted prices in multiple currencies

Route Stations Object

Organizes pickup and dropoff points by region:

{
  "Lusaka (Lusaka Province)": {
    "pickUpStations": ["LUSAKA:RGN:0"],
    "dropOffStations": ["LUSAKA:RGN:0"]
  },
  "Gauteng": {
    "pickUpStations": ["JOHANNESBURG:RGN:0", "MIDRAND:RGN:0", "PRETORIA:RGN:0"],
    "dropOffStations": ["JOHANNESBURG:RGN:0", "MIDRAND:RGN:0", "PRETORIA:RGN:0"]
  }
}

From/To Stop Objects

The fromStop, toStop, firstStop, and lastStop objects contain the same fields as items in the stopTimes array, providing quick access to key stops without iterating through the full route.

Settings Object

Route-specific configuration options:

Field	Type	Description
seatReservation	boolean	Whether seat selection is enabled
bulkTicketing	boolean	Whether bulk ticket purchases are allowed
sendTextMessage	boolean	Whether SMS confirmations are sent
flexibleTicketPrice	boolean	Whether dynamic pricing is enabled
flexibleOrigin	boolean	Whether passengers can board at any stop
flexibleDestination	boolean	Whether passengers can alight at any stop
allowOnlineSales	boolean	Whether online booking is permitted
enterCustomerName	boolean	Whether passenger name is required
enterCustomerPhoneNumber	boolean	Whether phone number is required
enterCustomerEmail	boolean	Whether email is required
enterCustomerNationality	boolean	Whether nationality is required
enterCustomerPassportNumber	boolean	Whether passport/ID number is required
noBetweenBookings	boolean	Whether intermediate stop bookings are disabled

---

Get Tickets

Retrieve tickets with various filters.

Endpoint: GET /api/ticket

Query Parameters:

• ticketId: Filter by ticket ID
• bookingReference: Filter by booking reference
• email: Filter by passenger email
• phoneNumber: Filter by phone number