Amazon Forecast
Developer Guide

This is prerelease documentation for a service in preview release. It is subject to change.

The Amazon Forecast API will undergo significant changes during scheduled maintenance occurring from 10 AM on 7/22/19 until 10 AM on 7/23/19. During maintenance, access to the Forecast APIs and console might be interrupted.

After 7/22/19, your Forecast resources (datasets, predictors, and forecasts) will no longer be available. However, you can save your forecasts for future use. We recommend using the CreateForecastExportJob API to save them to your S3 bucket before 7/22/19.

After maintenance concludes, before using the APIs, you must download a new SDK and modify your existing code to reflect the syntax changes. If you use only the console, you won’t need to make any changes.

We will provide new API documentation before scheduled maintenance begins. If you have questions, contact

Non-Parametric Time Series (NPTS) Recipe

The Amazon Forecast Non-Parametric Time Series (NPTS) recipe is a scalable, probabilistic baseline forecaster. It predicts the future value distribution of a given time series by sampling from past observations. The predictions are bounded by the observed values. NPTS is especially useful when the time series is intermittent (or sparse, containing many 0s) and bursty. For example, forecasting demand for individual items where the time series has many low counts. Amazon Forecast provides variants of NPTS that differ in which of the past observations are sampled and how they are sampled. To use an NPTS variant, you choose a hyperparameter setting.

How NPTS Works

Similar to classical forecasting methods, such as exponential smoothing (ETS) and autoregressive integrated moving average (ARIMA), NPTS generates predictions for each time series individually. The time series in the dataset can have different lengths. Currently, NPTS doesn't support missing values. The time points where the observations are available are called the training range and the time points where the prediction is desired are called the prediction range.

Amazon Forecast NPTS forecasters have the following variants: NTPS, seasonal NTPS, climatological forecaster, and seasonal climatological forecaster.


In this variant, predictions are generated by sampling from all observations in the training range of the time series. However, instead of uniformly sampling from all of the observations, this variant assigns weight to each of the past observations according to how far it is from the current time step where the prediction is needed. In particular, it uses weights that decay exponentially according to the distance of the past observations. In this way, the observations from the recent past are sampled with much higher probability than the observations from the distant past. This assumes that the near past is more indicative for the future than the distant past. You can control the amount of decay in the weights with the exp_kernel_weights hyperparameter.

To use this NPTS variant in Amazon Forecast, set the use_seasonal_model hyperparameter to False and accept all other default settings.

Seasonal NPTS

The seasonal NPTS variant is similar to NPTS except that instead of sampling from all of the observations, it uses only the observations from the past seasons . By default, the season is determined by the granularity of the time series. For example, for an hourly time series, to predict for hour t, this variant samples from the observations corresponding to the hour t on the previous days. Similar to NPTS, observation at hour t on the previous day is given more weight than the observations at hour t on earlier days. For more information about how to determine seasonality based on the granularity of the time series, see Seasonal Features.

If you provide time series features with the feat_dynamic_real hyperparameter, seasonality is determined by both the granularity and the feat_dynamic_real hyperparameter. To use only the feat_dynamic_real hyperparameter to define seasonality, set the use_seasonal_features hyperparameter to False.

To use the seasonal NPTS variant in Amazon Forecast, accept the default settings for all hyperparameters.

Climatological Forecaster

The climatological forecaster variant samples all of the past observations with uniform probability.

To use the climatological forecaster, set the kernel_type hyperparameter to uniform and the use_seasonal_model hyperparameter to False. Accept the default settings for all other hyperparameters.

Seasonal Climatological Forecaster

Similar to seasonal NPTS, the seasonal climatological forecaster samples the observations from past seasons, but samples them with uniform probability.

To use the seasonal climatological forecaster, set the kernel_type hyperparameter to uniform. Accept all other default settings for all of the other hyperparameters.

Seasonal Features

To determine what corresponds to a season for the seasonal NPTS and seasonal climatological forecaster, use the features listed in the following table. The table lists the derived features for the supported basic time frequencies, based on granularity. Amazon Forecast includes these feature time series, so you don't have to provide them.

Frequency of the Time Series Feature to Determine Seasonality
Minute minute-of-hour
Hour hour-of-day
Day day-of-week
Week day-of-month
Month month-of-year

When using the Amazon Forecast NPTS recipes, consider the following best practices for preparing the data and achieving optimal results:

  • Because NPTS generates predictions for each time series individually, provide the entire time series when calling the model for prediction. Also, accept the default value of the context_length hyperparameter. This causes the recipe to use the entire time series. If you change the context_length (because the training data is too long), make sure it is large enough and covers multiple past seasons. For example, for a daily time series, this value must be at least 365 days (provided that you have that amount of data).

  • If the data has seasonality patterns, the seasonal NPTS recipe typically works better. If external events, such as special holidays and promotions, have an effect on the time series, then provide those features in the feat_dynamic_real hyperparameter and use seasonal NPTS. In this case, you must also provide the feat_dynamic_real hyperparameter for both training and prediction ranges.

NPTS Hyperparameters

The following table lists the hyperparameters that you can use in the NPTS recipe.

Parameter Name Description

The number of time-steps that the model is trained to predict. This is also called the forecast horizon. The trained model always generates forecasts with this length.

The prediction_length is set from the ForecastHorizon parameter of the CreatePredictor API. It cannot be changed without retraining the model.



Valid values:

Positive integer



context_length The number of time-points in the past that the model uses for making the prediction. Providing a value for this parameter is optional. By default, it uses all of the time points in the training range. Typically, the value for this hyperparameter should be large and should cover multiple past seasons. For example, for the daily time series this value must be at least 365 days.


Valid values

Positive integer

Default value

The length of the training time series

kernel_type The kernel to use to define the weights used for sampling past observations.


Valid values

exponential or uniform

Default values


exp_kernel_weights If the kernel_type is exponential, the scaling parameter of the kernel. For faster (exponential) decay in the weights given to the observations in the distant past, use a large value.


Valid values

Positive real number

Default value


use_seasonal_model Whether to use a seasonal variant.


Valid values

True or False

Default value


se_default_time_features Whether to use seasonal features based on the granularity of the time series to determine seasonality. This parameter is valid only for the seasonal NPTS and seasonal climatological forecaster variants.


Valid values

True | False

Default value


num_samples The number of prediction samples generated per time series to compute the mean and quantiles.
Valid values


Default value


Tune NPTS Models

To choose the best NPTS variant, you can tune the following hyperparameters.

Parameter Name Values Comment
kernel_type {exponential, uniform}
use_seasonal_model {True, False}
exp_kernel_weights Positive real number Valid only if kernel_type is exponential
use_default_time_features {True, False} Valid only for seasonal NPTS and seasonal climatological forecaster variants