---
category: [Administration & Integrations, Platform and Product Extensions, Platform and Product Extensions/Integration, Administration & Integrations/Custom Integrations & Apps, Platform and Product Extensions/Workday Extend]
keyword: [Extend, Workday AI Gateway, AI Gateway]
nav: wcp_docs
parent_url: /wcp_docs/
title: Machine Learning Forecaster REST API
layout: subsection
---
The Machine Learning Forecaster REST API provides time series forecasting that’s critical in financial planning, sales projections, inventory management, and forecasting IT or project resources. The ML Forecaster API makes informed predictions about the future by analyzing patterns, trends, and seasonality in the given historical data. To predict future values based on the characteristics of your data, you can select any of these forecasting methods:
- Simple Exponential Smoothing - For data with consistent or slowly changing patterns, which typically has no clear seasonal pattern. Example: Sales forecasting for non-seasonal, staple items.
- Croston's Method - For data with irregular or intermittent demand patterns. The Croston’s method produces a single forecast and is suited for sparse data or intermittent data that has no clear trend or seasonality. Example: Sales forecasting for items with sporadic demand.
- Holt-Winters Additive Model - For data with constant seasonality over time. The Holt-Winters method captures seasonality and trend in the data. For the Holt-Winters additive model, the seasonality is assumed to have no significant change in magnitude each cycle. Example: Forecasting complex sales patterns with consistent sales and growth during the holiday seasons.
- Holt-Winters Multiplicative Model - For data with seasonal variations that change in proportion to the level of data. For the Holt-Winters multiplicative model, the magnitude of seasonality changes each cycle. Example: Forecasting sales data that increase or decrease proportionally during summer and winter seasons.
## URL Base Path
The ML Forecaster API endpoint uses this base URL:
```
https://api.workday.com/ml/forecaster/{version}
```
For regional URL base paths, see [Reference: Workday Extend API Gateways and Authorization Base URLs](/wcp_docs/dlh1653340161856.html)
## Security Considerations
For client tools such as Bruno, use the Bearer token for your tenant API access.
For Extend apps, see [Concept: Extend App Security](/wcp_docs/vel1628698852360.html).
## Prerequisites
- The Holt-Winters forecasting methods of the ML Forecaster API require a minimum of 2 full seasons of data to train the model and provide results. The number of values in the input `historic_data` must be at least 2 times the `seasonal_period_hint`.
## Predicting Data
To predict values using any of the forecasting methods, call this endpoint:
```
POST {baseURL}/predict
```
Required HTTP header:
```
content-type: application/json
```
In the request body, specify these required fields:
- `model_name` - Valid values (case-sensitive):
- `croston`
- `holt_winters`
- `ses`
- `forecast_params` - Contains the forecasting parameters:
- `horizon` - The number of periods to forecast. Minimum value is `1`. Maximum value is `1/3 * length-of-historic-data`.
- `model_params` - The parameters that are specific to the selected forecasting model.
If the model_name is:
model_params contains:
croston
model_params not required.
holt_winters additive
seasonality_mode - (Required) Set this value to "additive".
trend_mode - (Required) Set this value to "additive".
seasonal_periods_hint - (Required) The number of periods in a season. Minimum is 2. Maximum is 0.5 * length-of-historic-data.
holt_winters multiplicative
seasonality_mode - (Required) Set this value to "multiplicative".
trend_mode - (Required) Set this value to "multiplicative".
seasonal_periods_hint - (Required) The number of periods in a season. Minimum is 2. Maximum is 0.5 * length-of-historic-data.
ses
has_trend - (Optional) If true, the model assumes there is a trend in historic data, which reflects the Theta Model of simple exponential smoothing. The default is false, which represents the generic simple exponential smoothing with no trend.
- `data` - Contains the input historical data for the time series.
- `start_timestamp` - The start date and time of history data. Use the `yyyy-MM-dd hh:mm:ss` format. Minimum value is `1677-09-21 00:12:44`. Maximum value is `2262-04-11 23:47:15`.
- `granularity` - The data frequency. Valid values (case-sensitive):
- `D` - Daily.
- `W` - Weekly.
- `MS` - Month-start.
- `ME` - Month-end, equivalent to the previous value “M”.
- `YS` - Year-start.
- `YE` - Year-end, equivalent to the previous value “Y”.
- `QS` - Quarter-start.
- `QE` - Quarter-end, equivalent to the previous value “Q”.
Note: The ML Forecaster REST API supports both values for the month-end, year-end, and quarter-end frequencies. We recommend using the 2-character values, which are the standard values.
- `historic_data` - Contains the `values[]` list of either float or integer numbers. The minimum list size is:
- `9` - for forecasting with no seasonality.
- `11` - for forecasting with seasonality.
The maximum list size is 100,000.
The response returns the `results[]` list, which contains the predicted values and their corresponding timestamps. The maximum number of results is `1/3 * length-of-historic-data`.
## Example: Simple Exponential Smoothing
The Simple Exponential Smoothing method is typically used for data that has no clear seasonal pattern. An example of this dataset would be oil production from the OPEC region.
This sample uses the Simple Exponential Smoothing model (`"model_name": "ses"`) to forecast the values for the next 2 month-starts.
Sample request:
```
POST https://api.workday.com/ml/forecaster/v1/predict
```
Sample request body:
```
{
"model_name": "ses",
"forecast_params": {
"horizon": 2,
"model_params": {
"has_trend": false
}
},
"data": {
"start_timestamp": "2022-05-01T08:00:00",
"granularity": "MS",
"historic_data": {
"values": [
30.73, 31.17, 31.38, 32.22, 32.11, 32.09, 31.47, 31.39, 30.48, 30.61, 30.73, 30.74, 30.14
]
}
}
}
```
Sample response:
```
{
"results": [
{
"timestamp": "2023-06-01T08:00:00",
"value": 30.140000008940696
},
{
"timestamp": "2023-07-01T08:00:00",
"value": 30.140000008940696
}
],
"report": {
"forecast_time": 0.0073575968854129314
}
}
```
## Example: Holt-Winters Additive
The Holt-Winters method captures seasonality and trend in the data. For the Holt-Winters additive model, the seasonality is assumed to have no significant change in magnitude each cycle. An example of this is monthly total sales data.
This sample forecasts the values using the Holt-Winters additive mode (`"seasonality_mode": "multiplicative"`) with a cycle length of 4 periods.
Sample request:
```
POST https://api.workday.com/ml/forecaster/v1/predict
```
Sample request body:
```
{
"model_name": "holt_winters",
"forecast_params": {
"horizon": 4,
"model_params": {
"seasonal_periods_hint": 12,
"seasonality_mode": "additive"
}
},
"data": {
"start_timestamp": "2030-01-01T08:00:00",
"granularity": "MS",
"historic_data": {
"values": [9388, 8481, 9475, 9259, 9615, 9347,
8558, 8217, 8541, 10091, 11049, 12802,
9863, 9203, 10340, 10176, 10554, 10414,
10536, 10635, 10826, 11184, 12050, 13947
]
}
}
}
```
Sample response:
```
{
"results": [
{"timestamp": "2032-01-01T08:00:00", "value": 11431.749501177106},
{"timestamp": "2032-02-01T08:00:00", "value": 10636.197457516773},
{"timestamp": "2032-03-01T08:00:00", "value": 11732.716554598079},
{"timestamp": "2032-04-01T08:00:00", "value": 11574.418730137622}],
"report": {"forecast_time": 0.01719096199667547}
}
```
## Example: Holt-Winters Multiplicative
The Holt-Winters multiplicative model is when the magnitude of seasonality changes each cycle. An example of this is monthly gas production.
This sample forecasts the values using the Holt-Winters multiplicative mode (`"seasonality_mode": "multiplicative"`) for the next 4 month-starts.
Sample request:
```
POST https://api.workday.com/ml/forecaster/v1/predict
```
Sample request body:
```
{
"model_name": "holt_winters",
"forecast_params": {
"horizon": 4,
"model_params": {
"seasonal_periods_hint": 12,
"seasonality_mode": "multiplicative"
}
},
"data": {
"start_timestamp": "2030-01-01T08:00:00",
"granularity": "MS",
"historic_data": {
"values": [51367, 48073, 46251, 43736, 39975, 40478,
46895, 46147, 55011, 57799, 62450, 63896,
57784, 53231, 50354, 38410, 41600, 41471,
46287, 49013, 56624, 61739, 66600, 60054]
}
}
}
```
Sample response:.
```
{"results": [
{"timestamp": "2032-01-01T08:00:00", "value": 57232.52930644676},
{"timestamp": "2032-02-01T08:00:00", "value": 53117.518330710926},
{"timestamp": "2032-03-01T08:00:00", "value": 50637.37240907827},
{"timestamp": "2032-04-01T08:00:00", "value": 43356.01887375918}],
"report": {"forecast_time": 0.020125071998336352}}
```
## Example: Croston's Method
The Croston’s method produces a single forecast and is useful for sparse data or intermittent data that has no clear trend or seasonality. An example of this would be the daily sales for a particular SKU in a superstore.
This sample uses the Croston's method (`"model_name": "croston"`) to forecast the values for the next 6 week-ends.
Sample request:
```
POST https://api.workday.com/ml/forecaster/v1/predict
```
Sample request body:
```
{
"model_name": "croston",
"forecast_params": {
"horizon": 6
},
"data": {
"start_timestamp": "2023-11-01T08:00:00",
"granularity": "W",
"historic_data": {
"values": [
0, 0, 0, 29, 0, 0, 11, 0, 0, 0, 0, 0, 82
]
}
}
}
```
Sample response:
```
{
"results": [
{
"timestamp": "2024-02-04T08:00:00",
"value": 7.951338199513383
},
{
"timestamp": "2024-02-11T08:00:00",
"value": 7.951338199513383
},
{
"timestamp": "2024-02-18T08:00:00",
"value": 7.951338199513383
},
{
"timestamp": "2024-02-25T08:00:00",
"value": 7.951338199513383
},
{
"timestamp": "2024-03-03T08:00:00",
"value": 7.951338199513383
},
{
"timestamp": "2024-03-10T08:00:00",
"value": 7.951338199513383
}
],
"report": {
"forecast_time": 0.002357593970373273
}
}
```
## Limitations
The number of periods to forecast has a maximum of 1/3 the number of values in the historic data.
## Common Errors