Long-horizon forecasting is used to predict multiple seasonal cycles into the future. The TimeGPT model offers long-term forecasting capabilities by setting the parameter model="timegpt-1-long-horizon".

This page provides an overview of how to perform long-horizon forecasting using the Nixtla Client. You’ll also learn how to switch between default and Azure AI endpoints.

​
Overview

Long-horizon forecasting allows you to forecast beyond one full seasonal cycle. For example, if monthly data exhibits annual seasonality, you can project several years into the future. TimeGPT’s long-horizon variant can handle these extended forecasts.

1

Step 1 — Install and Import Libraries

Import Libraries
# Import Libraries
import pandas as pd
from nixtla import NixtlaClient
2

Step 2 — Initialize Nixtla Client

You can initialize the Nixtla Client by providing your API key:

Initialize Nixtla Client
nixtla_client = NixtlaClient(
    # defaults to os.environ.get("NIXTLA_API_KEY")
    api_key="my_api_key_provided_by_nixtla"
)

Use an Azure AI endpoint
To use an Azure AI endpoint, explicitly specify the base_url parameter:

Initialize Azure AI Client
nixtla_client = NixtlaClient(
    base_url="your azure ai endpoint",
    api_key="your api_key"
)
3

Step 3 — Load Data and Create Forecast

Load your time series data into a Pandas DataFrame, then call the forecast method:

Load Data and Create Forecast
# Load sample dataset
df = pd.read_csv(
    "https://raw.githubusercontent.com/Nixtla/transfer-learning-time-series/main/datasets/air_passengers.csv"
)

# Generate forecast
forecast_df = nixtla_client.forecast(
    df=df,
    h=36,
    model="timegpt-1-long-horizon",
    time_col="timestamp",
    target_col="value"
)
4

Step 4 — Review Logs

The Nixtla Client emits helpful messages and warnings during the forecasting process:

When the specified horizon h exceeds the model’s recommended horizon, the accuracy may be lower. Consider adjusting h based on your forecasting needs.

​
Model Options

If using an Azure AI endpoint, explicitly select the Azure model with:

Use Azure Model
nixtla_client.forecast(..., model="azureai")

timegpt-1

Default model for general forecasting tasks.

timegpt-1-long-horizon

For extended (long-horizon) forecasts.

azureai

For Nixtla services running on your Azure endpoint.

Refer to the Tutorial on Long-horizon Forecasting for best practices and guidance on choosing the right model for your use case.

For a comprehensive walkthrough on forecasting more than one season ahead, visit the complete tutorial on Long-horizon forecasting.