API Docs

API: Get All Trip Instances

Request

Retrieve all trip instances with a GET request:

GET /trip-instances

Available Query Parameters:

Parameter	Type	Description	Example
`trip_date`	Date	Filter by specific trip date (YYYY-MM-DD)	2025-08-17
`start_date`	Date	Start date for date range query	2025-08-01
`end_date`	Date	End date for date range query	2025-08-31
`status`	Integer	Filter by status (0: Inactive, 1: Active, 2: Migrated)	1
`coach_type`	Integer	Filter by coach type (1: AC, 2: Non-AC)	1
`coach_id`	Integer	Filter by specific coach	2
`route_id`	Integer	Filter by specific route	1
`today`	Boolean	Filter for today's trips only	true
`upcoming`	Boolean	Filter for upcoming trips	true
`past`	Boolean	Filter for past trips	true
`per_page`	Integer	Number of items per page (max: 100)	15
`sort_by`	String	Sort field (trip_date, created_at, etc.)	trip_date
`sort_order`	String	Sort order (asc, desc)	desc

Sample Response (Comprehensive Format):


{
  "status": "success",
  "code": 200,
  "message": "Trip instances retrieved successfully",
  "data": {
    "current_page": 1,
    "data": [
      {
        "id": 2,
        "trip_id": 2,
        "trip_date": "2025-08-17",
        "trip_date_formatted": "Sunday, August 17, 2025",
        "status": 1,
        "status_name": "Active",
        "coach_type": 1,
        "coach_type_name": "AC",
        "migrated_trip_id": null,
        "coach_id": 2,
        "coach": {
          "id": 2,
          "coach_no": "101",
          "seat_plan_id": 1,
          "coach_type": "1",
          "coach_type_name": "AC",
          "status": 1
        },
        "bus_id": 1,
        "bus": {
          "id": 1,
          "registration_number": "123",
          "manufacturer_company": "ad",
          "model_year": 2000,
          "color": null,
          "status": 1
        },
        "schedule_id": 1,
        "schedule": {
          "id": 1,
          "name": "11:00",
          "status": 0
        },
        "route_id": 1,
        "route": {
          "id": 1,
          "start_id": 2,
          "end_id": 2,
          "distance": 1300,
          "duration": "02:45",
          "status": "1",
          "start_district": {
            "id": 2,
            "name": "Updated District 1",
            "code": "UD1"
          },
          "end_district": {
            "id": 2,
            "name": "Updated District 1",
            "code": "UD1"
          },
          "route_display": "Updated District 1 → Updated District 1"
        },
        "driver_id": null,
        "driver": {
          "id": null,
          "name": null,
          "contact_no": null,
          "email": null,
          "license_no": null,
          "license_expired_date": null,
          "status": null
        },
        "supervisor_id": null,
        "supervisor": {
          "id": null,
          "name": null,
          "contact_no": null,
          "email": null,
          "status": null
        },
        "seat_plan_id": 1,
        "seat_plan": {
          "id": 1,
          "name": "Bus A",
          "floor": null,
          "rows": 6,
          "cols": 4,
          "layout_type": "2-2"
        },
        "total_seats": 24,
        "seat_inventory_summary": {
          "total_seats": 24,
          "available_seats": 24,
          "booked_seats": 0,
          "blocked_seats": 0,
          "occupancy_percentage": 0,
          "has_inventory": true
        },
        "is_ac": true,
        "is_active": true,
        "is_migrated": false,
        "migrated_trip": null,
        "created_by": 2,
        "updated_by": null,
        "migrated_by": null,
        "created_at": "2025-08-14T10:21:22.000000Z",
        "updated_at": "2025-08-14T10:21:22.000000Z"
      }
    ],
    "first_page_url": "http://127.0.0.1:8000/api/trip-instances?page=1",
    "from": 1,
    "last_page": 1,
    "last_page_url": "http://127.0.0.1:8000/api/trip-instances?page=1",
    "links": [
      {
        "url": null,
        "label": "« Previous",
        "active": false
      },
      {
        "url": "http://127.0.0.1:8000/api/trip-instances?page=1",
        "label": "1",
        "active": true
      },
      {
        "url": null,
        "label": "Next »",
        "active": false
      }
    ],
    "next_page_url": null,
    "path": "http://127.0.0.1:8000/api/trip-instances",
    "per_page": 15,
    "prev_page_url": null,
    "to": 2,
    "total": 2
  }
}

Response Structure Overview:

Core Trip Information

id / trip_id - Unique trip identifier
trip_date - Trip date (YYYY-MM-DD)
trip_date_formatted - Human-readable date
status - Numeric status (0/1/2)
status_name - Status description
coach_type - Coach type (1: AC, 2: Non-AC)
coach_type_name - Coach type description

Related Entities

coach - Coach details with number and type
bus - Bus registration and specifications
schedule - Time schedule information
route - Route with start/end districts
seat_plan - Seating arrangement details

Staff Information

driver - Driver details and license info
supervisor - Supervisor contact information

Seat Management

total_seats - Total available seats
seat_inventory_summary - Real-time seat status:
- available_seats
- booked_seats
- blocked_seats
- occupancy_percentage

Status Flags

is_ac - Boolean: AC coach
is_active - Boolean: Active trip
is_migrated - Boolean: Migrated trip

Route Information

start_district - Origin district details
end_district - Destination district details
route_display - Formatted route string
distance - Route distance
duration - Estimated travel time

Status Values:

Value	Status	Description
`0`	Inactive	Trip is disabled/cancelled
`1`	Active	Trip is active and bookable
`2`	Migrated	Trip has been migrated to another trip

Coach Types:

Value	Type	Description
`1`	AC	Air-conditioned coach
`2`	Non-AC	Non air-conditioned coach

Seat Inventory Status:

Value	Status	Description
`1`	Available	Seat is available for booking
`2`	Booked	Seat is confirmed and booked
`3`	Blocked	Seat is temporarily blocked
`0`	Cancelled	Seat booking was cancelled

Key Features:

Pagination Support

Standard Laravel pagination
Configurable per_page (max 100)
Full pagination metadata included

Date Range Queries

Single date filtering
Date range queries across partitions
Smart partition management

Real-time Data

Live seat availability
Occupancy percentages
Current booking status

Comprehensive Relations

All related entities included
District information with codes
Staff contact details

Example API Calls:


# Get all trips
GET /api/trip-instances

# Get trips for specific date
GET /api/trip-instances?trip_date=2025-08-17

# Get active AC trips
GET /api/trip-instances?status=1&coach_type=1

# Get trips for date range
GET /api/trip-instances?start_date=2025-08-01&end_date=2025-08-31

# Get today's trips only
GET /api/trip-instances?today=true

# Get upcoming trips with pagination
GET /api/trip-instances?upcoming=true&per_page=20&page=2