GreedyOptim API Integration Guide
Endpoints
GET /health
Response:
{
"status": "healthy",
"timestamp": "2025-11-25T00:17:15.053513",
"service": "greedyoptim-api"
}
GET /methods
Response:
{
"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)
{
"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