The-transit-Project/monitoring_ui/docs/transit_api/README.md

Transit API

Transit API voor het beheren van busroutes, navigatie en GPS tracking voor busbestuurders.

Project Structuur

transit_api/
├── index.js           # Main API endpoints
├── middleware.js      # JWT authentication middleware
├── db.js             # PostgreSQL connection
├── schema.sql        # Database schema setup
├── package.json      # Dependencies
└── .env              # Environment variables

Setup

1. Dependencies installeren

npm install

2. Database Schema opzetten

Voer het volgende uit in PostgreSQL:

# Via psql command line
psql -U your_user -d your_database -f schema.sql

Of kopieer-plak de SQL queries rechtstreeks in pgAdmin.

3. Environment variabelen (.env)

PG_HOST=localhost
PG_PORT=5432
PG_USER=your_user
PG_PASS=your_password
PG_DB=your_database
JWT_SECRET=your_jwt_secret
PORT=5001

Note: ADMIN_USER_CODES has been moved to the auth_api service. Configure admin user codes in auth_api/.env as a comma-separated list.

4. API starten

npm start

API draait op https://transit.xtransit.testinstance.nl

The service group also includes the Employee API at https://employees.xtransit.testinstance.nl and the central monitoring dashboard. See ../docs/MONITORING_UI.md for health checks, error inspection, and the controlled request tester.

API Endpoints

Alle endpoints vereisen een Authorization: Bearer {token} header.

GET /health

• Controleert of de gedeployde transit API draait en de database bereikbaar is.
• Geeft 200 met {"status":"ok","database":"ok"} bij succes.
• Geeft 503 als de API wel draait maar de database niet bereikbaar is.

Schedule

Schedules are weekly templates. Each row in transit.schedules represents one departure time for one bus line and one day_of_week:

• 1 to 5: weekdays
• 6: Saturday
• 0: Sunday

Driver assignments are stored separately in transit.shifts with (schedule_id, driver_id), where driver_id references workers.users(id). The current shifts shape represents the active assignment. To retain different assignments for different calendar weeks, add a week_start (or assignment date range) column and include it in the unique key.

GET /driver/schedules/daily?date=2026-09-18

• Returns only weekly schedule templates assigned to the authenticated driver through transit.shifts.

PATCH /driver/weekly-schedules/:scheduleId/status

• Updates the status of an assigned weekly schedule.

GET /admin/weekly-schedules

• Lists weekly templates and their current driver assignments.

GET /admin/shift-drivers

• Lists drivers from workers.users for shift assignment.

POST /admin/weekly-schedules

• Creates one template. Body: { "busLineId": 1, "dayOfWeek": 1, "startTime": "08:00", "endTime": "09:00", "driverId": 12 }.

POST /admin/weekly-schedules/bulk

• Creates multiple departures in one transaction. The API derives each end time from the selected bus line duration. Body: { "busLineId": 1, "dayOfWeeks": [1,2,3,4,5], "startTimes": ["06:00", "06:30", "07:00"], "driverId": 12 }.

PUT /admin/weekly-schedules/:scheduleId/shift

• Replaces the driver assignment. Pass { "driverId": 12 } or { "driverId": null }.

The legacy /admin/schedules and /schedule/daily endpoints remain for older clients, but new clients must use the weekly schedule endpoints above.

GET /schedule/daily?date=2024-05-05

• Ophalen van dagplanning voor chauffeur
• Response:

{
  "date": "2024-05-05",
  "routes": [
    {
      "id": 1,
      "startTime": "2024-05-05T08:00:00Z",
      "status": "scheduled",
      "busLine": {
        "lineNumber": 1,
        "startStop": "Central Station",
        "endStop": "Airport"
      },
      "busType": {
        "name": "Standard Bus",
        "seatCapacity": 50,
        "licensePlate": "BUS-001"
      }
    }
  ]
}

GET /routes/:routeId

• Details van een specifieke route
• Response: { "route": {...} }

Public Schedule Overview

GET /schedules/overview?date=2026-05-06&lineId=1

• Haalt een datum-gebonden overzicht op van geplande diensten
• Weekly templates are selected by day_of_week and driver assignments by shifts
• Incidentele diensten worden alleen meegenomen op hun exacte datum
• Filters: driverId/chauffeurId, stopId/busStopId, lineId, status
• Response: { "date": "2026-05-06", "summary": {...}, "schedules": [...] }

De legacy endpoint GET /schedules blijft beschikbaar voor bestaande clients.

Voorbeeld:

curl "https://transit.xtransit.testinstance.nl/schedules/overview?date=2026-05-06&chauffeurId=12&busStopId=3"

Navigation

POST /navigation/route

• Opslaan van berekende route van OSRM
• Body:

{
  "routeId": 1,
  "startLat": 52.5200,
  "startLon": 13.4050,
  "endLat": 52.5300,
  "endLon": 13.4150,
  "totalDistance": 15000,
  "totalDuration": 900,
  "geojson": {
    "type": "LineString",
    "coordinates": [[13.4050, 52.5200], ...]
  }
}

GET /bus-lines/:busLineId/stops

• Alle stops van een buslijn (voor navigatie waypoints)
• Response:

{
  "stops": [
    {
      "id": 1,
      "order": 1,
      "name": "Central Station",
      "latitude": 52.52,
      "longitude": 13.405
    }
  ]
}

GPS Tracking

POST /gps/track

• Real-time positie opslaan
• Body:

{
  "routeId": 1,
  "latitude": 52.521,
  "longitude": 13.406,
  "speed": 45.5,
  "heading": 180,
  "accuracy": 5.0
}

GET /gps/route/:routeId

• Alle opgeslagen positie punten van een route
• Response:

{
  "positions": [
    {
      "id": 1,
      "latitude": 52.521,
      "longitude": 13.406,
      "speed": 45.5,
      "heading": 180,
      "recordedAt": "2024-05-05T08:15:00Z"
    }
  ]
}

Route Status

PATCH /routes/:routeId/status

• Update route status
• Body: { "status": "in_progress" }
• Valid statuses: scheduled, in_progress, completed, cancelled

Admin

Alle admin-endpoints vereisen naast een geldig JWT-token ook dat je userCode voorkomt in ADMIN_USER_CODES.

POST /admin/stops

• Maak een herbruikbare stop aan
• Body:

{
  "name": "Central Station",
  "latitude": 52.52,
  "longitude": 13.405
}

POST /admin/bus-lines/:busLineId/stops

• Koppel een bestaande stop aan een buslijn
• Body:

{
  "stopId": 1,
  "stopOrder": 1,
  "estimatedArrivalMinutes": 0
}

Database Schema

bus_types

• id - Primary key
• name - Bus type name (Standard Bus, etc.)
• seat_capacity - Number of seats
• license_plate - Unique license plate

bus_lines

• id - Primary key
• line_number - Unique line number (1, 5, 12, etc.)
• start_stop - Start stop name
• end_stop - End stop name
• estimated_duration_minutes - Expected route duration

stops

• id - Primary key
• name - Stop name
• latitude, longitude - Stop location

route_stops

• id - Primary key
• bus_line_id - Which bus line the stop belongs to
• stop_id - Reusable stop reference
• stop_order - Stop sequence on that bus line
• estimated_arrival_minutes - Optional ETA per stop

routes

• id - Primary key
• user_id - Chauffeur (references workers.users)
• bus_line_id - Which line (references bus_lines)
• bus_type_id - Which bus (references bus_types)
• start_time - Scheduled start
• status - scheduled/in_progress/completed/cancelled

navigation_routes

• id - Primary key
• route_id - Link to route (unique)
• polyline_geojson - GeoJSON LineString van de route
• total_distance_meters - Route distance
• total_duration_seconds - Estimated duration

gps_tracking

• id - Primary key
• route_id - Which route
• latitude, longitude - Current position
• speed_kmh - Current speed
• recorded_at - Timestamp

Integration met Flutter App

// In schedule_service.dart

// Save navigation route
await scheduleService.saveNavigationRoute(
  routeId: 1,
  navRoute: navigationRoute,
);

// Track GPS
await scheduleService.trackGPS(
  routeId: 1,
  currentPos: navigationPoint,
  speed: 45.5,
  heading: 180,
);

// Update route status
await scheduleService.updateRouteStatus(1, 'in_progress');

Error Handling

Alle endpoints retourneren error responses:

{
  "error": "error_code",
  "details": "More information"
}

Common errors:

• missing_token - No Authorization header
• invalid_token - Token verification failed
• missing_required_fields - Required data missing
• invalid_status - Invalid status value
• route_not_found - Route not found
• unauthorized - User doesn't own this resource