Overview
The ML Prediction API provides machine learning-powered demand forecasting for vehicle segments. It predicts monthly sales demand based on vehicle characteristics (brand, model, line) using time series models trained on historical transaction data.
Base URL
https://your-domain.com/v1/ml
Predict Demand
Generates a demand forecast for a specific vehicle segment.
Authentication: Required (JWT or internal service key)
Authorization: Configurable permissions (default: requires valid token)
Request Body
Type of vehicle: CAR or MOTORCYCLE
Vehicle brand/manufacturer (e.g., “Toyota”, “Yamaha”)
Model year (e.g., “2022”, “2023”)
Vehicle line/variant (e.g., “Corolla”, “MT-09”)
Forecast horizon in months (1-24)
Confidence level for prediction intervals (0.5-0.99)
{
"vehicle_type": "CAR",
"brand": "Toyota",
"model": "2022",
"line": "Corolla",
"horizon_months": 6,
"confidence": 0.95
}
Response
Array of monthly predictions
Predicted demand (point estimate)
Lower confidence interval bound
Upper confidence interval bound
Version identifier of the model used
Model performance metrics (MAE, RMSE, etc.)
{
"predictions": [
{
"month": "2026-04",
"demand": 8.5,
"lower_ci": 5.2,
"upper_ci": 11.8
},
{
"month": "2026-05",
"demand": 9.2,
"lower_ci": 5.8,
"upper_ci": 12.6
},
{
"month": "2026-06",
"demand": 10.1,
"lower_ci": 6.5,
"upper_ci": 13.7
},
{
"month": "2026-07",
"demand": 9.8,
"lower_ci": 6.2,
"upper_ci": 13.4
},
{
"month": "2026-08",
"demand": 10.5,
"lower_ci": 6.8,
"upper_ci": 14.2
},
{
"month": "2026-09",
"demand": 11.2,
"lower_ci": 7.4,
"upper_ci": 15.0
}
],
"model_version": "v1.2.3-20260301",
"metrics": {
"mae": 1.45,
"rmse": 2.12,
"mape": 0.15
}
}
Status Codes
200 OK - Prediction generated successfully400 Bad Request - Invalid input parameters401 Unauthorized - Missing or invalid authentication403 Forbidden - Insufficient permissions404 Not Found - No model available or segment not found500 Internal Server Error - Model prediction failed
Example
curl -X POST https://your-domain.com/v1/ml/predict \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"vehicle_type": "CAR",
"brand": "Toyota",
"model": "2022",
"line": "Corolla",
"horizon_months": 6,
"confidence": 0.95
}'
Predict with Historical Data
POST /v1/ml/predict-with-history
Request Body
Same as the /predict endpoint.
{
"vehicle_type": "CAR",
"brand": "Toyota",
"model": "2022",
"line": "Corolla",
"horizon_months": 6,
"confidence": 0.95
}
Response
Array of future monthly predictions
Array of historical sales data points
Actual sales count for that month
Model training timestamp (ISO 8601)
Model performance metrics
{
"predictions": [
{
"month": "2026-04",
"demand": 8.5,
"lower_ci": 5.2,
"upper_ci": 11.8
},
{
"month": "2026-05",
"demand": 9.2,
"lower_ci": 5.8,
"upper_ci": 12.6
}
],
"history": [
{
"month": "2025-01",
"sales_count": 7.0
},
{
"month": "2025-02",
"sales_count": 9.0
},
{
"month": "2025-03",
"sales_count": 8.0
},
{
"month": "2025-04",
"sales_count": 10.0
},
{
"month": "2025-05",
"sales_count": 11.0
},
{
"month": "2025-06",
"sales_count": 9.0
},
{
"month": "2025-07",
"sales_count": 12.0
},
{
"month": "2025-08",
"sales_count": 10.0
},
{
"month": "2025-09",
"sales_count": 11.0
},
{
"month": "2025-10",
"sales_count": 13.0
},
{
"month": "2025-11",
"sales_count": 9.0
},
{
"month": "2025-12",
"sales_count": 8.0
},
{
"month": "2026-01",
"sales_count": 10.0
},
{
"month": "2026-02",
"sales_count": 11.0
},
{
"month": "2026-03",
"sales_count": 9.0
}
],
"segment": {
"vehicle_type": "CAR",
"brand": "Toyota",
"model": "2022",
"line": "Corolla"
},
"model_version": "v1.2.3-20260301",
"trained_at": "2026-03-01T08:00:00Z",
"metrics": {
"mae": 1.45,
"rmse": 2.12,
"mape": 0.15
}
}
Use Case
This endpoint is ideal for:
- Charting historical vs. predicted sales
- Analyzing trends and seasonality
- Validating predictions against recent history
- Dashboards and reporting
Status Codes
Same as /predict endpoint.
Example
curl -X POST https://your-domain.com/v1/ml/predict-with-history \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"vehicle_type": "CAR",
"brand": "Toyota",
"model": "2022",
"line": "Corolla",
"horizon_months": 6
}'
Understanding Predictions
Point Estimate
The demand field represents the model’s best estimate of monthly sales.
Confidence Intervals
The lower_ci and upper_ci fields provide prediction intervals:
- With
confidence=0.95 (default), there’s a 95% probability that actual demand will fall within [lower_ci, upper_ci]
- Wider intervals indicate higher uncertainty
- Intervals typically widen for longer forecast horizons
Example Interpretation
{
"month": "2026-04",
"demand": 8.5,
"lower_ci": 5.2,
"upper_ci": 11.8
}
Validation Rules
Vehicle Type
Must be exactly CAR or MOTORCYCLE (case-sensitive).
Line Field
The line field is required and must not be empty after whitespace trimming.
Horizon Months
- Minimum: 1 month
- Maximum: 24 months
- Default: 6 months
Confidence Level
- Minimum: 0.5 (50%)
- Maximum: 0.99 (99%)
- Default: 0.95 (95%)
Model Metrics
When available, the response includes model performance metrics:
Mean Absolute Error - Average prediction error magnitude
Root Mean Square Error - Standard deviation of prediction errors
Mean Absolute Percentage Error - Average error as percentage
Authentication Options
JWT Bearer Token
Standard authentication for user-facing applications:
curl -H "Authorization: Bearer YOUR_JWT_TOKEN" ...
Internal Service Key
For service-to-service communication:
curl -H "X-Internal-Service-Key: YOUR_INTERNAL_KEY" ...
Never expose the internal service key in client-side applications or public repositories.
Error Responses
400 Bad Request - Invalid Vehicle Type
{
"detail": [
{
"loc": ["body", "vehicle_type"],
"msg": "vehicle_type must be CAR or MOTORCYCLE",
"type": "value_error"
}
]
}
400 Bad Request - Invalid Horizon
{
"detail": [
{
"loc": ["body", "horizon_months"],
"msg": "ensure this value is less than or equal to 24",
"type": "value_error.number.not_le"
}
]
}
404 Not Found - No Model Available
{
"detail": "No trained model available. Please train a model first."
}
404 Not Found - Segment Not Found
{
"detail": "No historical data found for the specified vehicle segment"
}
500 Internal Server Error
{
"detail": "Model prediction failed: insufficient training data"
}
- Predictions are typically generated in < 500ms
- Historical data queries may take longer for segments with extensive history
- Consider caching predictions for frequently requested segments
- Predictions are deterministic for the same model version and inputs