Step 1: Create a TimeGPT account and generate your API key

  • Go to dashboard.nixtla.io
  • Sign in with Google, GitHub or your email
  • Create your API key by going to โ€˜API Keysโ€™ in the menu and clicking on โ€˜Create New API Keyโ€™
  • Your new key will appear. Copy the API key using the button on the right.

Step 2: Install Nixtla

In your favorite Python development environment:

Install nixtla with pip:

pip install nixtla

Step 3: Import the Nixtla TimeGPT client

from nixtla import NixtlaClient

You can instantiate the NixtlaClient class providing your authentication API key.

nixtla_client = NixtlaClient(
    api_key = 'my_api_key_provided_by_nixtla'
)

Check your API key status with the validate_api_key method.

nixtla_client.validate_api_key()
True

This will get you started, but for more secure usage, see Setting Up your API Key.

Step 4: Start making forecasts!

Now you can start making forecasts! Letโ€™s import an example using the classic AirPassengers dataset. This dataset contains the monthly number of airline passengers in Australia between 1949 and 1960. First, load the dataset and plot it:

import polars as pl
df = pl.read_csv(
    'https://raw.githubusercontent.com/Nixtla/transfer-learning-time-series/main/datasets/air_passengers.csv',
    try_parse_dates=True,
)
df.head()
timestampvalue
datei64
1949-01-01112
1949-02-01118
1949-03-01132
1949-04-01129
1949-05-01121
nixtla_client.plot(df, time_col='timestamp', target_col='value')

๐Ÿ“˜ Data Requirements

  • Make sure the target variable column does not have missing or non-numeric values.
  • Do not include gaps/jumps in the timestamps (for the given frequency) between the first and late timestamps. The forecast function will not impute missing dates.
  • The time column should be of type Date or Datetime.

For further details go to Data Requeriments.

Forecast a longer horizon into the future

Next, forecast the next 12 months using the SDK forecast method. Set the following parameters:

  • df: A pandas DataFrame containing the time series data.
  • h: Horizons is the number of steps ahead to forecast.
  • freq: The polars offset alias, see the possible values here.
  • time_col: The column that identifies the datestamp.
  • target_col: The variable to forecast.
timegpt_fcst_df = nixtla_client.forecast(df=df, h=12, freq='1mo', time_col='timestamp', target_col='value')
timegpt_fcst_df.head()
INFO:nixtla.nixtla_client:Validating inputs...
INFO:nixtla.nixtla_client:Querying model metadata...
INFO:nixtla.nixtla_client:Preprocessing dataframes...
INFO:nixtla.nixtla_client:Restricting input...
INFO:nixtla.nixtla_client:Calling Forecast Endpoint...
timestampTimeGPT
datef64
1961-01-01437.837921
1961-02-01426.062714
1961-03-01463.116547
1961-04-01478.244507
1961-05-01505.646484
nixtla_client.plot(df, timegpt_fcst_df, time_col='timestamp', target_col='value')

You can also produce longer forecasts by increasing the horizon parameter and selecting the timegpt-1-long-horizon model. Use this model if you want to predict more than one seasonal period of your data.

For example, letโ€™s forecast the next 36 months:

timegpt_fcst_df = nixtla_client.forecast(df=df, h=36, time_col='timestamp', target_col='value', freq='1mo', model='timegpt-1-long-horizon')
timegpt_fcst_df.head()
INFO:nixtla.nixtla_client:Validating inputs...
INFO:nixtla.nixtla_client:Querying model metadata...
WARNING:nixtla.nixtla_client:The specified horizon "h" exceeds the model horizon. This may lead to less accurate forecasts. Please consider using a smaller horizon.
INFO:nixtla.nixtla_client:Preprocessing dataframes...
INFO:nixtla.nixtla_client:Restricting input...
INFO:nixtla.nixtla_client:Calling Forecast Endpoint...
timestampTimeGPT
datef64
1961-01-01436.843414
1961-02-01419.351532
1961-03-01458.943146
1961-04-01477.876068
1961-05-01505.656921
nixtla_client.plot(df, timegpt_fcst_df, time_col='timestamp', target_col='value')

Produce a shorter forecast

You can also produce a shorter forecast. For this, we recommend using the default model, timegpt-1.

timegpt_fcst_df = nixtla_client.forecast(df=df, h=6, time_col='timestamp', target_col='value', freq='1mo')
nixtla_client.plot(df, timegpt_fcst_df, time_col='timestamp', target_col='value')
INFO:nixtla.nixtla_client:Validating inputs...
INFO:nixtla.nixtla_client:Preprocessing dataframes...
INFO:nixtla.nixtla_client:Restricting input...
INFO:nixtla.nixtla_client:Calling Forecast Endpoint...