Get Schedules Endpoint With Extra Information (V2)

✅ CURRENT VERSION - This endpoint supports both Timed Schedules and Random Schedules.

Please, bear in mind that this endpoint is for businesses/merchants that don't want to go through a process flow like: (Fetch routes -> Choose bus -> Select Date -> Select schedule -> Select bus seats, etc) before you user can make purchase.

So, what this endpoint does is that if you don't want to allow users to go through the process of choosing bus, selecting date, selecting schedule, etc, it provides you with a list of default routes/schedules so that you show to your customer so that when they click it, you can go ahead to call the buy ticket endpoint and reduce the entire process flow.

Understanding Schedule Types

This endpoint returns schedules for both types of transport operations:

Timed Schedules

Fixed departure times that work perfectly for formal transport companies operating long-distance routes. For example:

• GUO Transport (Lagos to Abuja): 8-hour journey with strict 6 AM departure

• Passengers must arrive on time or miss the bus

• Creates predictability for business travelers and long-distance journeys

• Response includes a single bus object and fixed time with departure and arrival

Random Schedules

Flexible timing for informal transport businesses operating shorter routes. For example:

• Star Sunny Motors (Awka to Nnewi): 1-hour journey with flexible timing

• Passengers can arrive throughout the day and find buses leaving soon

• Operates with time windows rather than fixed departure times

• Response includes multiple buses array and operating_hours instead of fixed times

Example of Random Schedule structure:

• Morning Operations (5 AM - 12 PM): Shuttle buses (7 passengers) at ₦1,500 per person

• Evening Operations (12 PM - 10 PM): Hiace buses (14 passengers) at ₦1,200 per person

Endpoint Overview

This V2 endpoint retrieves comprehensive schedule information for any route, supporting both Timed and Random schedules. It provides all the information needed to proceed directly to ticket purchase, including schedule IDs, bus details, available seats, route information, terminal details, and business information.

Key Features

• Supports both Timed and Random schedules - unified endpoint for all schedule types

• Customizable query parameters to get exactly the information needed

• Returns schedule_id and bus information for immediate ticket purchase

• schedule_type field indicates whether each schedule is "timed" or "random"

• Different response structure based on schedule type (see Response section)

• Special note: Always pass the departure date to avoid requiring customers to change dates after purchase via email request

API Reference

Endpoint

GET /api/v2/merpi/transport/schedules/packages

Query Parameters

Parameter	Type	Required	Description	Example
route_id	Integer	No	ID of the route to fetch schedules for	11
departure_date	String	Recommended	Departure date (format: YYYY-MM-DD). Highly recommended to avoid post-purchase date changes	2024-12-25
from_city_id	Integer	No	ID of the city where the trip originates	12
to_city_id	Integer	No	ID of the destination city	3
business_id	String (UUID)	No	ID of the business offering the schedule	6e9d9432-2a1d-4a8a-a5e4-3ddfaf832523
terminal_id	Integer	No	ID of the terminal associated with the departure	7

Request & Response Example

Get bus schedules by route, departure and arrival city, terminal ID, business ID and departure date (V2 - Supports both Timed and Random schedules)

get

This endpoint retrieves available bus schedules based on the provided route ID, departure and arrival city ID, terminal ID, business ID and departure date. This V2 endpoint supports both Timed Schedules (fixed departure times) and Random Schedules (flexible timing with operating windows). The response structure varies based on the schedule_type field.

Seat Availability Note: For timed schedules, the available_seats array in the bus object is only included when the departure_date parameter is provided. This array shows the real-time seat layout and availability for the specified date, allowing users to see which seats are already booked and select from available seats. Without the departure_date parameter, seat availability information is not included.

Query parameters

route_idintegerOptional

ID of the route to fetch schedules for.

departure_datestring · dateOptional

Departure date for which to retrieve schedules (format: YYYY-MM-DD). Important: When this parameter is provided for timed schedules, the response includes the available_seats array in the bus object, showing the seat layout with real-time availability for that specific date. This allows users to see which seats are already booked and select from available seats.

from_city_idintegerOptional

ID of the city where the trip originates.

Example: 6

to_city_idintegerOptional

ID of the destination city.

Example: 8

business_idstringOptional

ID of the business offering the schedule (UUID format).

Example: 61e634bc-028c-4e33-a83f-7f77d5befc70

terminal_idintegerOptional

ID of the terminal associated with the departure.

Example: 3

Responses

200

List of bus schedules (both Timed and Random).

application/json

successbooleanOptionalExample: true

statusintegerOptionalExample: 200

messagestringOptionalExample: List of bus schedules

400

Bad request due to invalid input parameters.

application/json

404

No schedules found matching the criteria.

application/json

500

Internal server error.

application/json

get

/api/v2/merpi/transport/schedules/packages

HTTPcURLJavaScriptPython

GET /api/v2/merpi/transport/schedules/packages HTTP/1.1
Accept: */*

{
  "success": true,
  "status": 200,
  "message": "List of bus schedules",
  "data": {
    "schedules": [
      {
        "id": 1,
        "name": "Schedule 1",
        "slug": "NNEWI_IYANA_IPAJA_HAICE_2_TRANSPORT_COMPANY_1",
        "from": "Nnewi",
        "to": "Iyana-Ipaja",
        "days": {
          "monday": 1,
          "tuesday": 1,
          "wednesday": 1,
          "thursday": 1,
          "friday": 1,
          "saturday": 1,
          "sunday": 0
        },
        "route": {
          "id": 4,
          "price": 15500,
          "schedule_type": "timed",
          "from": {
            "address": "12, Nnnewi Road",
            "city": {
              "id": 6,
              "name": "Nnewi",
              "state": {
                "id": 4,
                "name": "Anambra"
              }
            }
          },
          "to": {
            "address": "12, Iyana Ipaja Road",
            "city": {
              "id": 8,
              "name": "Iyana-Ipaja",
              "state": {
                "id": 24,
                "name": "Lagos"
              }
            }
          }
        },
        "terminal": {
          "id": 3,
          "name": "Unizik termsite",
          "address": "No 7 Prince Ogele Street Eliowhani",
          "location": "Anambra",
          "slug": null
        },
        "business": {
          "id": "61e634bc-028c-4e33-a83f-7f77d5befc70",
          "name": "Transport company",
          "photo": "https://dev.syticks.com/storage/profilePhotos/qr3JZSnpxxxNKQ7mbaBS0P00qejPzxXp7tQ8rgtM.jpg",
          "slug": "transport-company",
          "type": "bus"
        },
        "time": {
          "departure": "06:00 AM",
          "arrival": "06:00 AM"
        },
        "bus": {
          "id": 3,
          "name": "Haice 2",
          "image": "https://test.merpi.syticks.com/storage/transport/buses/WKOnEqQT4vLWkZVhbdQdghwWm3CZKmObMbCMahfs.jpg",
          "seats": 16,
          "price": "0",
          "available_seats": [
            [
              {
                "id": 25,
                "seat": true,
                "row": 1,
                "column": 1,
                "available": true
              },
              {
                "id": 26,
                "seat": false,
                "row": 1,
                "column": 2,
                "available": false
              },
              {
                "id": 27,
                "seat": true,
                "row": 1,
                "column": 3,
                "available": true
              },
              {
                "id": 28,
                "seat": true,
                "row": 1,
                "column": 4,
                "available": true
              }
            ],
            [
              {
                "id": 29,
                "seat": true,
                "row": 2,
                "column": 1,
                "available": true
              },
              {
                "id": 30,
                "seat": true,
                "row": 2,
                "column": 2,
                "available": true
              },
              {
                "id": 31,
                "seat": true,
                "row": 2,
                "column": 3,
                "available": true
              },
              {
                "id": 32,
                "seat": false,
                "row": 2,
                "column": 4,
                "available": false
              }
            ],
            [
              {
                "id": 33,
                "seat": true,
                "row": 3,
                "column": 1,
                "available": true
              },
              {
                "id": 34,
                "seat": true,
                "row": 3,
                "column": 2,
                "available": true
              },
              {
                "id": 35,
                "seat": true,
                "row": 3,
                "column": 3,
                "available": true
              },
              {
                "id": 36,
                "seat": false,
                "row": 3,
                "column": 4,
                "available": false
              }
            ],
            [
              {
                "id": 37,
                "seat": true,
                "row": 4,
                "column": 1,
                "available": true
              },
              {
                "id": 38,
                "seat": true,
                "row": 4,
                "column": 2,
                "available": true
              },
              {
                "id": 39,
                "seat": true,
                "row": 4,
                "column": 3,
                "available": true
              },
              {
                "id": 40,
                "seat": true,
                "row": 4,
                "column": 4,
                "available": true
              }
            ]
          ],
          "total_seats": 16
        },
        "amount": "15500",
        "price_breakdown": {
          "ticket_price": 15000,
          "convenience_fee": 100,
          "merchant_commission": 400
        }
      },
      {
        "id": 31,
        "name": "",
        "slug": "EKWULOBIA_OWERRI_HAICE_BUMPER_GOOD_RIDE_41",
        "from": "Ekwulobia",
        "to": "Owerri",
        "days": {
          "monday": 1,
          "tuesday": 1,
          "wednesday": 1,
          "thursday": 1,
          "friday": 1,
          "saturday": 1,
          "sunday": 1
        },
        "route": {
          "id": 42,
          "price": 31.5,
          "schedule_type": "random",
          "from": {
            "address": "Achivers school, unity Avenue",
            "city": {
              "id": 2,
              "name": "Ekwulobia",
              "state": {
                "id": 4,
                "name": "Anambra"
              }
            }
          },
          "to": {
            "address": "Oke ureje",
            "city": {
              "id": 9,
              "name": "Owerri",
              "state": {
                "id": 16,
                "name": "Imo"
              }
            }
          }
        },
        "terminal": {
          "id": 12,
          "name": "Onitsha Terminal",
          "address": "Onitsha main market",
          "location": "Anambra",
          "slug": "onitsha-terminal"
        },
        "business": {
          "id": "26838f1e-b6c2-43e7-9dd4-3409512fff64",
          "name": "Good Ride",
          "photo": "https://dev.syticks.com/storage/profilePhotos/hdwLJbfhtSWvfcibcHePKCbZ87bL2xnSkaENgsVw.jpg",
          "slug": "good-ride",
          "type": "bus"
        },
        "amount": "31.5",
        "price_breakdown": {
          "ticket_price": 30,
          "convenience_fee": 0.6,
          "merchant_commission": 0.9
        },
        "buses": [
          {
            "bus_id": 9,
            "start_time": "04:15:00",
            "end_time": "12:30:00",
            "bus_type": "Haice Bumper",
            "price": "31.5",
            "image": "https://test.merpi.syticks.com/storage/transport/buses/kdBtxtVWE6p6Z8YnIVuqPwUPElglGpsHByEIZOZ4.jpg"
          }
        ],
        "operating_hours": {
          "start": "04:15:00",
          "end": "12:30:00"
        }
      }
    ],
    "next_page": null,
    "count": 2,
    "per_page": 20
  }
}

Response Fields

Common Fields (Both Schedule Types)

Field	Type	Description
schedules	Array	List of available bus schedules (both Timed and Random)
id	Integer	Schedule ID (use for buy ticket endpoint)
name	String	Schedule name
slug	String	Unique schedule identifier
schedule_type	String	"timed" or "random" - indicates the schedule type
from / to	String	Departure and arrival cities
days	Object	Operating days (1 = active, 0 = inactive)
route	Object	Complete route details including addresses and city information
route.price	Number	Base route price
terminal	Object	Departure terminal information
business	Object	Transport company details
next_page	String/Null	Pagination cursor for next page
count	Integer	Total number of schedules
per_page	Integer	Results per page (default: 20)

Timed Schedule Specific Fields

Field	Type	Description
time	Object	Fixed departure and arrival times
time.departure	String	Fixed departure time (e.g., "07:00 AM")
time.arrival	String	Expected arrival time (e.g., "03:00 PM")
bus	Object	Single bus information for this timed schedule
bus.id	Integer	Bus ID
bus.name	String	Bus name/type
bus.image	String	Bus image URL
bus.seats	Integer	Total number of seats
bus.price	Number	Additional bus-specific pricing (if any)
amount	Integer	Total ticket amount for this schedule

Random Schedule Specific Fields

Field	Type	Description
buses	Array	List of buses operating during different time windows
buses[].bus_id	Integer	Bus ID for this time window
buses[].start_time	String	Start of operating window for this bus(24-hour format: "06:00:00")
buses[].end_time	String	End of operating window for this bus(24-hour format: "23:36:00")
buses[].bus_type	String	Type/name of the bus
buses[].price	String	This is the price of this bus - and the price you must use for the route for random schedules.
buses[].image	String	Bus image URL
operating_hours	Object	Overall operating hours for the schedule
operating_hours.start	String	Earliest departure time (24-hour format)
operating_hours.end	String	Latest departure time (24-hour format)

Understanding the Response Structure

How to Identify Schedule Type

Check the schedule_type field in each schedule object:

if (schedule.schedule_type === "timed") {
  // Use schedule.time.departure and schedule.time.arrival
  // Use schedule.bus for bus information
  // Show fixed departure time to customer
} else if (schedule.schedule_type === "random") {
  // Use schedule.buses array for available buses
  // Use schedule.operating_hours for time windows
  // Show flexible timing to customer
}

For Timed Schedules:

• Present the fixed departure time from time.departure

• Show the single bus option from bus

• Emphasize that customers must arrive on time

For Random Schedules:

• Present the operating hours from operating_hours

• Show multiple bus options from buses array with their time windows

• Emphasize flexible departure within the operating window

Important Notes

1. Departure Date: Always include the departure_date parameter to ensure customers don't need to change dates after purchase

2. Schedule Type Detection: Always check the schedule_type field to determine how to parse the response

3. Timed vs Random: Timed schedules have a bus object and time field; Random schedules have buses array and operating_hours

4. Schedule ID: The id field from the response is required for the buy ticket endpoint

5. Operating Days: Use the days object to show customers which days the schedule operates

Integration Examples

Handling Mixed Results

const response = await fetch('/api/v2/merpi/transport/schedules/packages?...');
const data = await response.json();

data.data.schedules.forEach(schedule => {
  if (schedule.schedule_type === 'timed') {
    console.log(`Timed: ${schedule.name} departs at ${schedule.time.departure}`);
    console.log(`Bus: ${schedule.bus.name} with ${schedule.bus.seats} seats`);
  } else if (schedule.schedule_type === 'random') {
    console.log(`Random: ${schedule.name}`);
    console.log(`Operating hours: ${schedule.operating_hours.start} - ${schedule.operating_hours.end}`);
    schedule.buses.forEach(bus => {
      console.log(`- ${bus.bus_type}: ${bus.start_time} to ${bus.end_time}`);
    });
  }
});

Migration from V1

If you're migrating from the V1 endpoint:

1. Update Endpoint URL: Change /api/v1/... to /api/v2/...

2. Add Schedule Type Check: Implement logic to handle both schedule_type values

3. Handle Different Response Structures:

   • Check for bus vs buses

   • Check for time vs operating_hours

4. Update UI: Show appropriate information based on schedule type

5. Test Both Types: Ensure your integration works with both Timed and Random schedules