| # GreedyOptim API Integration Guide | |
| ## Endpoints | |
| ### GET /health | |
| Response: | |
| ```json | |
| { | |
| "status": "healthy", | |
| "timestamp": "2025-11-25T00:17:15.053513", | |
| "service": "greedyoptim-api" | |
| } | |
| ``` | |
| --- | |
| ### GET /methods | |
| Response: | |
| ```json | |
| { | |
| "available_methods": { | |
| "ga": { | |
| "name": "Genetic Algorithm", | |
| "description": "Evolutionary optimization using selection, crossover, and mutation", | |
| "typical_time": "medium", | |
| "solution_quality": "high" | |
| }, | |
| "cmaes": { | |
| "name": "CMA-ES", | |
| "description": "Covariance Matrix Adaptation Evolution Strategy", | |
| "typical_time": "medium-high", | |
| "solution_quality": "very high" | |
| }, | |
| "pso": { | |
| "name": "Particle Swarm Optimization", | |
| "description": "Swarm intelligence-based optimization", | |
| "typical_time": "medium", | |
| "solution_quality": "high" | |
| }, | |
| "sa": { | |
| "name": "Simulated Annealing", | |
| "description": "Probabilistic optimization inspired by metallurgy", | |
| "typical_time": "medium", | |
| "solution_quality": "medium-high" | |
| }, | |
| "nsga2": { | |
| "name": "NSGA-II", | |
| "description": "Non-dominated Sorting Genetic Algorithm (multi-objective)", | |
| "typical_time": "high", | |
| "solution_quality": "very high" | |
| }, | |
| "adaptive": { | |
| "name": "Adaptive Optimizer", | |
| "description": "Automatically selects best algorithm", | |
| "typical_time": "high", | |
| "solution_quality": "very high" | |
| }, | |
| "ensemble": { | |
| "name": "Ensemble Optimizer", | |
| "description": "Runs multiple algorithms in parallel", | |
| "typical_time": "high", | |
| "solution_quality": "highest" | |
| } | |
| }, | |
| "default_method": "ga", | |
| "recommended_for_speed": "ga", | |
| "recommended_for_quality": "ensemble" | |
| } | |
| ``` | |
| --- | |
| ## POST /schedule - Full Schedule Response Structure | |
| The `/schedule` endpoint returns a comprehensive schedule with service blocks and timing details. | |
| ### Response Structure Overview | |
| ``` | |
| FullScheduleResponse | |
| ├── schedule_id: string | |
| ├── generated_at: string (ISO datetime) | |
| ├── valid_from: string (ISO datetime) | |
| ├── valid_until: string (ISO datetime) | |
| ├── depot: string | |
| ├── trainsets: TrainsetScheduleResponse[] | |
| ├── fleet_summary: FleetSummaryResponse | |
| ├── optimization_metrics: OptimizationMetricsResponse | |
| └── alerts: AlertResponse[] | |
| ``` | |
| --- | |
| ### TrainsetScheduleResponse | |
| Each trainset in the schedule has the following structure: | |
| | Field | Type | Description | | |
| |-------|------|-------------| | |
| | `trainset_id` | string | Unique identifier (e.g., "TS-001") | | |
| | `status` | string | Current status: `REVENUE_SERVICE`, `STANDBY`, `MAINTENANCE` | | |
| | `readiness_score` | float | Score from 0.0 to 1.0 indicating operational readiness | | |
| | `daily_km_allocation` | float | Planned kilometers for the day | | |
| | `cumulative_km` | float | Total kilometers accumulated | | |
| | `assigned_duty` | string? | Duty assignment identifier | | |
| | `priority_rank` | int? | Priority ranking for service assignment | | |
| | `service_blocks` | ServiceBlockResponse[]? | List of assigned service blocks (for REVENUE_SERVICE) | | |
| | `stabling_bay` | string? | Assigned stabling bay (for STANDBY) | | |
| | `standby_reason` | string? | Reason for standby status | | |
| | `maintenance_type` | string? | Type of maintenance: `PREVENTIVE`, `CORRECTIVE`, `OVERHAUL` | | |
| | `ibl_bay` | string? | IBL bay assignment (for MAINTENANCE) | | |
| | `estimated_completion` | string? | Estimated maintenance completion time | | |
| | `alerts` | string[]? | List of alerts for this trainset | | |
| --- | |
| ### ServiceBlockResponse | |
| Service blocks represent scheduled work periods for a trainset: | |
| | Field | Type | Description | | |
| |-------|------|-------------| | |
| | `block_id` | string | Unique block identifier (e.g., "BLK-001") | | |
| | `departure_time` | string | Block start time (HH:MM format) | | |
| | `origin` | string | Starting station | | |
| | `destination` | string | Ending station | | |
| | `trip_count` | int | Number of trips in this block | | |
| | `estimated_km` | float | Total kilometers for this block | | |
| | `journey_time_minutes` | float? | Total journey time in minutes | | |
| | `period` | string? | Time period: `EARLY_MORNING`, `MORNING_PEAK`, `MIDDAY`, `EVENING_PEAK`, `LATE_EVENING` | | |
| | `is_peak` | bool | Whether this is a peak hour block | | |
| | `trips` | TripResponse[]? | Detailed trip information | | |
| --- | |
| ### TripResponse | |
| Each trip within a service block: | |
| | Field | Type | Description | | |
| |-------|------|-------------| | |
| | `trip_id` | string | Unique trip identifier | | |
| | `trip_number` | int | Sequential trip number | | |
| | `direction` | string | Direction: `UP` or `DOWN` | | |
| | `origin` | string | Origin station | | |
| | `destination` | string | Destination station | | |
| | `departure_time` | string | Departure time (HH:MM) | | |
| | `arrival_time` | string | Arrival time (HH:MM) | | |
| | `stops` | StationStopResponse[] | List of all station stops | | |
| --- | |
| ### StationStopResponse | |
| Each station stop within a trip: | |
| | Field | Type | Description | | |
| |-------|------|-------------| | |
| | `station_code` | string | Station code (e.g., "ALV") | | |
| | `station_name` | string | Full station name (e.g., "Aluva") | | |
| | `arrival_time` | string? | Arrival time at this station | | |
| | `departure_time` | string? | Departure time from this station | | |
| | `distance_from_origin_km` | float | Distance from trip origin in km | | |
| | `platform` | int? | Platform number | | |
| --- | |
| ### FleetSummaryResponse | |
| | Field | Type | Description | | |
| |-------|------|-------------| | |
| | `total_trainsets` | int | Total number of trainsets in fleet | | |
| | `revenue_service` | int | Number in revenue service | | |
| | `standby` | int | Number on standby | | |
| | `maintenance` | int | Number in maintenance | | |
| | `availability_percent` | float | Fleet availability percentage | | |
| --- | |
| ### OptimizationMetricsResponse | |
| | Field | Type | Description | | |
| |-------|------|-------------| | |
| | `fitness_score` | float | Overall optimization fitness score | | |
| | `method` | string | Optimization method used (ga, pso, cmaes, etc.) | | |
| | `mileage_variance_coefficient` | float | Variance in mileage distribution | | |
| | `total_planned_km` | float | Total planned kilometers for the day | | |
| | `optimization_runtime_ms` | int | Time taken for optimization in milliseconds | | |
| --- | |
| ### AlertResponse | |
| | Field | Type | Description | | |
| |-------|------|-------------| | |
| | `trainset_id` | string | Trainset this alert relates to | | |
| | `severity` | string | Alert severity: `LOW`, `MEDIUM`, `HIGH`, `CRITICAL` | | |
| | `alert_type` | string | Type of alert | | |
| | `message` | string | Human-readable alert message | | |
| --- | |
| ## Example Response (Simplified) | |
| ```json | |
| { | |
| "schedule_id": "SCH-20251202-001", | |
| "generated_at": "2025-12-02T10:30:00", | |
| "valid_from": "2025-12-02T05:00:00", | |
| "valid_until": "2025-12-02T23:30:00", | |
| "depot": "Muttom Depot", | |
| "trainsets": [ | |
| { | |
| "trainset_id": "TS-001", | |
| "status": "REVENUE_SERVICE", | |
| "readiness_score": 0.95, | |
| "daily_km_allocation": 280.5, | |
| "cumulative_km": 125000.0, | |
| "assigned_duty": "DUTY-A1", | |
| "priority_rank": 1, | |
| "service_blocks": [ | |
| { | |
| "block_id": "BLK-001", | |
| "departure_time": "06:00", | |
| "origin": "Aluva", | |
| "destination": "Pettah", | |
| "trip_count": 4, | |
| "estimated_km": 104.8, | |
| "journey_time_minutes": 180, | |
| "period": "MORNING_PEAK", | |
| "is_peak": true, | |
| "trips": [ | |
| { | |
| "trip_id": "TRIP-001", | |
| "trip_number": 1, | |
| "direction": "DOWN", | |
| "origin": "Aluva", | |
| "destination": "Pettah", | |
| "departure_time": "06:00", | |
| "arrival_time": "06:45", | |
| "stops": [ | |
| { | |
| "station_code": "ALV", | |
| "station_name": "Aluva", | |
| "arrival_time": null, | |
| "departure_time": "06:00", | |
| "distance_from_origin_km": 0.0, | |
| "platform": 1 | |
| }, | |
| { | |
| "station_code": "PTH", | |
| "station_name": "Pettah", | |
| "arrival_time": "06:45", | |
| "departure_time": null, | |
| "distance_from_origin_km": 26.2, | |
| "platform": 2 | |
| } | |
| ] | |
| } | |
| ] | |
| } | |
| ], | |
| "alerts": [] | |
| }, | |
| { | |
| "trainset_id": "TS-015", | |
| "status": "STANDBY", | |
| "readiness_score": 0.88, | |
| "daily_km_allocation": 0.0, | |
| "cumulative_km": 98000.0, | |
| "stabling_bay": "BAY-03", | |
| "standby_reason": "Reserve for peak hours", | |
| "alerts": [] | |
| }, | |
| { | |
| "trainset_id": "TS-020", | |
| "status": "MAINTENANCE", | |
| "readiness_score": 0.0, | |
| "daily_km_allocation": 0.0, | |
| "cumulative_km": 150000.0, | |
| "maintenance_type": "PREVENTIVE", | |
| "ibl_bay": "IBL-02", | |
| "estimated_completion": "2025-12-03T14:00:00", | |
| "alerts": ["Scheduled wheel profiling"] | |
| } | |
| ], | |
| "fleet_summary": { | |
| "total_trainsets": 25, | |
| "revenue_service": 18, | |
| "standby": 4, | |
| "maintenance": 3, | |
| "availability_percent": 88.0 | |
| }, | |
| "optimization_metrics": { | |
| "fitness_score": 0.92, | |
| "method": "ga", | |
| "mileage_variance_coefficient": 0.08, | |
| "total_planned_km": 4850.0, | |
| "optimization_runtime_ms": 1250 | |
| }, | |
| "alerts": [ | |
| { | |
| "trainset_id": "TS-007", | |
| "severity": "MEDIUM", | |
| "alert_type": "CERTIFICATE_EXPIRY", | |
| "message": "Safety certificate expires in 5 days" | |
| } | |
| ] | |
| } | |
| ``` | |
| Why Use Blocks Instead of Individual Trips? | |
| Crew Scheduling - A crew can be assigned to a block, not individual trips | |
| Efficiency - Easier to manage and optimize at block level | |
| Peak Hour Management - Blocks can be marked as is_peak: true to differentiate peak vs off-peak operations | |
| Mileage Tracking - Each block has estimated_km for easy daily mileage calculation |