Skip to main content

​
TimeGPT - Foundation Model for Time Series Forecasting

TimeGPT is a production-ready generative pretrained transformer for time series forecasting and predictions. It delivers accurate forecasts for retail sales, electricity demand, financial markets, and IoT sensor data with just a few lines of Python code. This quickstart guide will have you making your first forecast in under 5 minutes!

​
Set Up TimeGPT for Python Time Series Forecasting

​
Step 1: Get an 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 for TimeGPT API keys

TimeGPT dashboard showing API key management interface for Python forecasting

​
Step 2: Install Nixtla

Install the Nixtla library in your preferred Python environment: 
pip install nixtla

​
Step 3: Import the Nixtla TimeGPT client

Import the Nixtla client and instantiate it with your API key: 
from nixtla import NixtlaClient

nixtla_client = NixtlaClient(
    api_key='my_api_key_provided_by_nixtla'
)

​
Step 4: Load your time series data

Import the Nixtla client and instantiate it with your API key: 
from nixtla import NixtlaClient

nixtla_client = NixtlaClient(
    api_key='my_api_key_provided_by_nixtla'
)
Verify the status and validity of your API key: 
nixtla_client.validate_api_key()

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

​
Make Your First Time Series Forecast

We’ll demonstrate TimeGPT’s forecasting capabilities using the classic AirPassengers dataset, a monthly time series showing international airline passengers from 1949 to 1960. 
import pandas as pd

df = pd.read_csv('https://raw.githubusercontent.com/Nixtla/transfer-learning-time-series/main/datasets/air_passengers.csv')
df.head()
timestampvalue
01949-01-01112
11949-02-01118
21949-03-01132
31949-04-01129
41949-05-01121
If you are using your own data, here are the data requirements:
  • The target variable must not contain missing or non-numeric values.
  • The timestamp column must not contain missing values.
  • Date stamps must form a continuous sequence without gaps for the selected frequency.
  • pandas must be able to parse the timestamp column as datetime objects. (see Pandas documentation).
For more details, visit Data Requirements.
Plot the dataset: 
nixtla_client.plot(df, time_col='timestamp', target_col='value')
Time Series Plot

Historical AirPassengers time series data visualization showing monthly passenger trends from 1949 to 1960

The plot method automatically displays figures in notebook environments. To save a plot locally: 
fig = nixtla_client.plot(df, time_col='timestamp', target_col='value')
fig.savefig('plot.png', bbox_inches='tight')

​
Real-World Forecasting Applications

TimeGPT excels at:
  • Retail forecasting: Predict product demand and inventory needs
  • Energy forecasting: Forecast electricity consumption and renewable energy production
  • Financial forecasting: Project revenue, sales, and market trends
  • IoT predictions: Anticipate sensor readings and equipment metrics

​
Short and Long-Term Forecasting Examples

​
Generate a longer-term forecast

Forecast the next 12 months using the SDK’s forecast method: 
timegpt_fcst_df = nixtla_client.forecast(
    df=df,
    h=12,
    freq='MS',
    time_col='timestamp',
    target_col='value'
)
timegpt_fcst_df.head()
Plot the forecast: 
nixtla_client.plot(df, timegpt_fcst_df, time_col='timestamp', target_col='value')
Forecasted Plot

TimeGPT 12-month forecast visualization with confidence intervals for AirPassengers dataset

You may also generate forecasts for longer horizons with the timegpt-1-long-horizon model. For example, 36 months ahead: 
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 the forecast: 
nixtla_client.plot(df, timegpt_fcst_df, time_col='timestamp', target_col='value')
Longer Forecast Plot

TimeGPT long-horizon model 36-month forecast with extended prediction intervals

​
Generate a shorter-term forecast

Forecast the next 6 months with a single command: 
timegpt_fcst_df = nixtla_client.forecast(
    df=df,
    h=6,
    freq='MS',
    time_col='timestamp',
    target_col='value'
)
Plot the forecast: 
nixtla_client.plot(df, timegpt_fcst_df, time_col='timestamp', target_col='value')
Shorter Forecast Plot

TimeGPT 6-month short-term forecast for AirPassengers with prediction confidence bands

​
Frequently Asked Questions

​
How accurate is TimeGPT for forecasting?

TimeGPT achieves state-of-the-art accuracy across multiple domains including retail, finance, and electricity forecasting with zero-shot learning.

​
Can I use TimeGPT with my own time series data?

Yes, TimeGPT works with any time series data in pandas DataFrame format with a timestamp and target value column.

​
How long does it take to generate forecasts?

TimeGPT typically generates forecasts in seconds, making it suitable for production environments.

​
Next Steps

Now that you’ve made your first forecast, explore these tutorials to unlock TimeGPT’s full capabilities: