Quickstart

Learn how to use TimeGPT for accurate time series forecasting in just a few steps

TimeGPT is a production-ready generative pretrained transformer for time series. It can accurately predict domains such as retail, electricity, finance, and IoT with just a few lines of code. Get started below!

Implementation Guide

1. Create a TimeGPT account and generate your API key

   • Visit dashboard.nixtla.io to activate your free trial and create an account.
   • Sign in using Google, GitHub, or your email.
   • Navigate to API Keys in the menu and select Create New API Key.
   • Your new API key will appear on the screen. Copy this key using the button on the right.

   

   Dashboard displaying TimeGPT API keys and controls.
2. Install Nixtla

   Install the Nixtla library in your preferred Python environment:

   Install Nixtla

   pip install nixtla
   

3. Import the Nixtla TimeGPT client

   Import the Nixtla client and instantiate it with your API key:

   Nixtla Client Setup

   from nixtla import NixtlaClient
   
   nixtla_client = NixtlaClient(
       api_key='my_api_key_provided_by_nixtla'
   )
   

   Verify the status and validity of your API key:

   Validate API Key

   nixtla_client.validate_api_key()
   

   API Validation Output

   Validation Log Output

   INFO:nixtla.nixtla_client:Happy Forecasting! :), If you have questions or need support, please email [e-mail]
   
   True
   

   Important: For enhanced security practices, see our guide on Setting Up your API Key.

Start making forecasts!

1. Load the AirPassengers Dataset

We will use the classic AirPassengers dataset to demonstrate forecasts.

2. Preview the Dataset

Quickly examine structures like timestamps and values before forecasting.

3. Plot the Time Series

Visualize historical data to understand trends or seasonality.

Load AirPassengers Data

import pandas as pd

df = pd.read_csv('https://raw.githubusercontent.com/Nixtla/transfer-learning-time-series/main/datasets/air_passengers.csv')
df.head()

	timestamp	value
0	1949-01-01	112
1	1949-02-01	118
2	1949-03-01	132
3	1949-04-01	129
4	1949-05-01	121

Plot the dataset:

Plot AirPassengers Data

nixtla_client.plot(df, time_col='timestamp', target_col='value')

Historical AirPassengers data from 1949 to 1960.

Data Requirements

• The target variable must not contain missing or non-numeric values.
• Date stamps must form a continuous sequence without gaps for the selected frequency.
• Pandas should correctly parse the timestamp column (see Pandas documentation).
• The forecast method does not fill or handle missing dates.

For more details, visit Data Requirements.

Saving Figures from TimeGPT

The plot method automatically displays figures in notebook environments. To save a plot locally:

Save Figure Example

fig = nixtla_client.plot(df, time_col='timestamp', target_col='value')
fig.savefig('plot.png', bbox_inches='tight')

Short and Long-Term Forecasting Examples

Generate a longer-term forecast

Forecast the next 12 months using the SDK’s forecast method:

Forecast 12 Months

timegpt_fcst_df = nixtla_client.forecast(
    df=df,
    h=12,
    freq='MS',
    time_col='timestamp',
    target_col='value'
)
timegpt_fcst_df.head()

Display the forecast:

Plot 12 Month Forecast

nixtla_client.plot(df, timegpt_fcst_df, time_col='timestamp', target_col='value')

12-month forecast for AirPassengers data.

You may also generate forecasts for longer horizons with the timegpt-1-long-horizon model. For example, 36 months ahead:

Forecast 36 Months Long Horizon

timegpt_fcst_df = nixtla_client.forecast(
    df=df,
    h=36,
    freq='MS',
    time_col='timestamp',
    target_col='value',
    model='timegpt-1-long-horizon'
)
timegpt_fcst_df.head()

Plot 36 Month Forecast

nixtla_client.plot(df, timegpt_fcst_df, time_col='timestamp', target_col='value')

36-month forecast using the 'timegpt-1-long-horizon' model.

Generate a shorter-term forecast

Forecast the next 6 months with a single command:

Forecast 6 Months

timegpt_fcst_df = nixtla_client.forecast(
    df=df,
    h=6,
    freq='MS',
    time_col='timestamp',
    target_col='value'
)
nixtla_client.plot(df, timegpt_fcst_df, time_col='timestamp', target_col='value')

6-month forecast for AirPassengers data.