---
title: "Indices"
description: "Learn how to request and handle indices in the research environment in QuantConnect"
canonical: https://www.quantconnect.com/docs/v2/research-environment/datasets/indices
markdown: https://www.quantconnect.com/docs/v2/research-environment/datasets/indices.md
language: python
source: https://github.com/QuantConnect/Documentation/tree/master/04%20Research%20Environment/03%20Datasets/20%20Indices
modified: 2026-10-30
index: https://www.quantconnect.com/llms.txt
---

# Indices

[Documentation](https://www.quantconnect.com/docs/v2.md) > [Research Environment](https://www.quantconnect.com/docs/v2/research-environment.md) > Datasets > Indices

> Code examples are shown in Python. Append `?lang=csharp` to this URL for the C# version of this page.

## Introduction

This page explains how to request, manipulate, and visualize historical Index data.

## Create Subscriptions

Follow these steps to subscribe to an Index security:

1. Create a `QuantBook`.
   ```python
   qb = QuantBook()
   ```
2. Call the `add_index` method with a ticker and then save a reference to the Index `Symbol`.
   ```python
   spx = qb.add_index("SPX").symbol
   vix = qb.add_index("VIX").symbol
   ```

To view all of the available indices, see [Supported Indices](https://www.quantconnect.com/docs/v2/writing-algorithms/datasets/quantconnect/cash-indices.md#10-Supported-Indices).

## Get Historical Data

You need a [subscription](https://www.quantconnect.com/docs/v2/research-environment/datasets/indices.md#03-Create-Subscriptions) before you can request historical data for a security. On the time dimension, you can request an amount of historical data based on a trailing number of bars, a trailing period of time, or a defined period of time. On the security dimension, you can request historical data for a single Index, a subset of the Indices you created subscriptions for in your notebook, or all of the Indices in your notebook.

### Trailing Number of Bars

To get historical data for a number of trailing bars, call the `history` method with the `Symbol` object(s) and an integer.

```python
# DataFrame
single_history_df = qb.history(spx, 10)
single_history_trade_bar_df = qb.history(TradeBar, spx, 10)
subset_history_df = qb.history([spx, vix], 10)
subset_history_trade_bar_df = qb.history(TradeBar, [spx, vix], 10)
all_history_df = qb.history(qb.securities.keys(), 10)
all_history_trade_bar_df = qb.history(TradeBar, qb.securities.keys(), 10)

# Slice objects
all_history_slice = qb.history(10)

# TradeBar objects
single_history_trade_bars = qb.history[TradeBar](spx, 10)
subset_history_trade_bars = qb.history[TradeBar]([spx, vix], 10)
all_history_trade_bars = qb.history[TradeBar](qb.securities.keys(), 10)
```

The preceding calls return the most recent bars, excluding periods of time when the exchange was closed.

### Trailing Period of Time

To get historical data for a trailing period of time, call the `history` method with the `Symbol` object(s) and a `timedelta`.

```python
# DataFrame of trade data (indices don't have quote data)
single_history_df = qb.history(spx, timedelta(days=3))
subset_history_df = qb.history([spx, vix], timedelta(days=3))
all_history_df = qb.history(qb.securities.keys(), timedelta(days=3))

# Slice objects
all_history_slice = qb.history(timedelta(days=3))

# TradeBar objects
single_history_trade_bars = qb.history[TradeBar](spx, timedelta(days=3))
subset_history_trade_bars = qb.history[TradeBar]([spx, vix], timedelta(days=3))
all_history_trade_bars = qb.history[TradeBar](qb.securities.keys(), timedelta(days=3))
```

The preceding calls return the most recent bars, excluding periods of time when the exchange was closed.

### Defined Period of Time

To get historical data for a specific period of time, call the `history` method with the `Symbol` object(s), a start `datetime`, and an end `datetime`. The start and end times you provide are based in the [notebook time zone](https://www.quantconnect.com/docs/v2/research-environment/initialization.md#04-Set-Time-Zone).

```python
start_time = datetime(2021, 1, 1)
end_time = datetime(2021, 2, 1)

# DataFrame of trade data (indices don't have quote data)
single_history_df = qb.history(spx, start_time, end_time)
subset_history_df = qb.history([spx, vix], start_time, end_time)
all_history_df = qb.history(qb.securities.keys(), start_time, end_time)

# TradeBar objects
single_history_trade_bars = qb.history[TradeBar](spx, start_time, end_time)
subset_history_trade_bars = qb.history[TradeBar]([spx, vix], start_time, end_time)
all_history_trade_bars = qb.history[TradeBar](qb.securities.keys(), start_time, end_time)
```

The preceding calls return the bars that have a timestamp within the defined period of time.

## Resolutions

The following table shows the available resolutions and data formats for Index subscriptions:

| Resolution | TradeBar | QuoteBar | Trade Tick | Quote Tick |
| --- | --- | --- | --- | --- |
| `TICK` | Not supported | Not supported | Not supported | Not supported |
| `SECOND` | Supported for SPX, NDX, and VIX only⚠︎ | Not supported | Not supported | Not supported |
| `MINUTE` | Supported✓ | Not supported | Not supported | Not supported |
| `HOUR` | Supported✓ | Not supported | Not supported | Not supported |
| `DAILY` | Supported✓ | Not supported | Not supported | Not supported |

⚠︎ Supported for SPX, NDX, and VIX only.

## Markets

The only market available for Indices is `Market.USA`.

## Data Normalization

The data normalization mode doesn't affect data from history request. If you change the data normalization mode, it won't change the outcome.

## Wrangle Data

You need some [historical data](https://www.quantconnect.com/docs/v2/research-environment/datasets/indices.md#04-Get-Historical-Data) to perform wrangling operations. The process to manipulate the historical data depends on its data type. To display `pandas` objects, run a cell in a notebook with the `pandas` object as the last line. To display other data formats, call the `print` method.

### DataFrame Objects

If the `history` method returns a `DataFrame`, the first level of the `DataFrame` index is the [encoded Index Symbol](https://www.quantconnect.com/docs/v2/writing-algorithms/key-concepts/security-identifiers.md#02-Encoding-Symbols) and the second level is the `end_time` of the data sample. The columns of the `DataFrame` are the data properties.

| symbol | time | close | high | low | open |
| --- | --- | --- | --- | --- | --- |
| VIX 31 | 2021-01-04 02:16:00 | 23.02 | 23.04 | 23.02 | 23.04 |
| VIX 31 | 2021-01-04 02:17:00 | 23.04 | 23.05 | 23.02 | 23.02 |
| VIX 31 | 2021-01-04 02:18:00 | 23.07 | 23.08 | 23.05 | 23.05 |
| VIX 31 | 2021-01-04 02:19:00 | 23.03 | 23.05 | 23.03 | 23.05 |
| VIX 31 | 2021-01-04 02:20:00 | 23.05 | 23.05 | 23.04 | 23.04 |
| ... | ... | ... | ... | ... | ... |
| SPX 31 | 2021-01-29 15:16:00 | 3714.24 | 3714.24 | 3714.24 | 3714.24 |
| SPX 31 | 2021-01-29 15:17:00 | 3714.24 | 3714.24 | 3714.24 | 3714.24 |
| SPX 31 | 2021-01-29 15:18:00 | 3714.24 | 3714.24 | 3714.24 | 3714.24 |
| SPX 31 | 2021-01-29 15:19:00 | 3714.24 | 3714.24 | 3714.24 | 3714.24 |
| SPX 31 | 2021-01-29 15:20:00 | 3714.24 | 3714.24 | 3714.24 | 3714.24 |

To select the historical data of a single Index, index the `loc` property of the `DataFrame` with the Index `Symbol`.

```python
all_history_df.loc[spx]  # or all_history_df.loc['SPX']
```

| time | close | high | low | open |
| --- | --- | --- | --- | --- |
| 2021-01-04 02:16:00 | 3714.24 | 3714.24 | 3714.24 | 3714.24 |
| 2021-01-04 02:17:00 | 3714.24 | 3714.24 | 3714.24 | 3714.24 |
| 2021-01-04 02:18:00 | 3714.24 | 3714.24 | 3714.24 | 3714.24 |
| 2021-01-04 02:19:00 | 3714.24 | 3714.24 | 3714.24 | 3714.24 |
| 2021-01-04 02:20:00 | 3714.24 | 3714.24 | 3714.24 | 3714.24 |
| ... | ... | ... | ... | ... |
| 2021-01-29 15:16:00 | 3714.24 | 3714.24 | 3714.24 | 3714.24 |
| 2021-01-29 15:17:00 | 3714.24 | 3714.24 | 3714.24 | 3714.24 |
| 2021-01-29 15:18:00 | 3714.24 | 3714.24 | 3714.24 | 3714.24 |
| 2021-01-29 15:19:00 | 3714.24 | 3714.24 | 3714.24 | 3714.24 |
| 2021-01-29 15:20:00 | 3714.24 | 3714.24 | 3714.24 | 3714.24 |

To select a column of the `DataFrame`, index it with the column name.

```python
all_history_df.loc[spx]['close']
```

```python
time
2021-01-04 02:16:00    3714.24
2021-01-04 02:17:00    3714.24
2021-01-04 02:18:00    3714.24
2021-01-04 02:19:00    3714.24
2021-01-04 02:20:00    3714.24
                         ...
2021-01-29 15:16:00    3714.24
2021-01-29 15:17:00    3714.24
2021-01-29 15:18:00    3714.24
2021-01-29 15:19:00    3714.24
2021-01-29 15:20:00    3714.24
Name: close, dtype: float64
```

If you request historical data for multiple Indices, you can transform the `DataFrame` so that it's a time series of close values for all of the Indices. To transform the `DataFrame`, select the column you want to display for each Index and then call the [unstack](https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.unstack.html) method.

```python
all_history_df['close'].unstack(level=0)
```

The `DataFrame` is transformed so that the column indices are the `Symbol` of each Index and each row contains the close value.

| symbol time | SPX 31 | VIX 31 |
| --- | --- | --- |
| 2021-01-04 02:16:00 | 3714.24 | 23.02 |
| 2021-01-04 02:17:00 | 3714.24 | 23.04 |
| 2021-01-04 02:18:00 | 3714.24 | 23.07 |
| 2021-01-04 02:19:00 | 3714.24 | 23.03 |
| 2021-01-04 02:20:00 | 3714.24 | 23.05 |
| ... | ... | ... |
| 2021-01-29 15:16:00 | 3714.24 | NaN |
| 2021-01-29 15:17:00 | 3714.24 | NaN |
| 2021-01-29 15:18:00 | 3714.24 | NaN |
| 2021-01-29 15:19:00 | 3714.24 | NaN |
| 2021-01-29 15:20:00 | 3714.24 | NaN |

### Slice Objects

If the `history` method returns `Slice` objects, iterate through the `Slice` objects to get each one. The `Slice` objects may not have data for all of your Index subscriptions. To avoid issues, check if the `Slice` contains data for your Index before you index it with the Index `Symbol`.

```python
for slice in all_history_slice:
        if slice.bars.contains_key(spx):
        trade_bar = slice.bars[spx]
```

You can also iterate through each `TradeBar` in the `Slice`.

```python
for slice in all_history_slice:
    for kvp in slice.bars:
        symbol = kvp.key
        trade_bar = kvp.value
```

### TradeBar Objects

If the `history` method returns `TradeBar` objects, iterate through the `TradeBar` objects to get each one.

```python
for trade_bar in single_history_trade_bars:
    print(trade_bar)
```

If the `history` method returns `TradeBars`, iterate through the `TradeBars` to get the `TradeBar` of each Index. The `TradeBars` may not have data for all of your Index subscriptions. To avoid issues, check if the `TradeBars` object contains data for your security before you index it with the Index `Symbol`.

```python
for trade_bars in all_history_trade_bars:
    if trade_bars.contains_key(spx):
        trade_bar = trade_bars[spx]
```

You can also iterate through each of the `TradeBars`.

```python
for trade_bars in all_history_trade_bars:
    for kvp in trade_bars:
        symbol = kvp.key
        trade_bar = kvp.value
```

## Plot Data

You need some [historical Indices data](https://www.quantconnect.com/docs/v2/research-environment/datasets/indices.md#04-Get-Historical-Data) to produce plots. You can use many of the [supported plotting libraries](https://www.quantconnect.com/docs/v2/research-environment/charting.md) to visualize data in various formats. For example, you can plot candlestick and line charts.

### Candlestick Chart

Follow these steps to plot candlestick charts:

1. Get some [historical data](https://www.quantconnect.com/docs/v2/research-environment/datasets/indices.md#04-Get-Historical-Data).
   ```python
   history = qb.history(spx, datetime(2021, 11, 24), datetime(2021, 12, 8), Resolution.DAILY).loc[spx]
   ```
2. Import the `plotly` library.
   ```python
   import plotly.graph_objects as go
   ```
3. Create a `Candlestick`.
   ```python
   candlestick = go.Candlestick(x=history.index,
                                open=history['open'],
                                high=history['high'],
                                low=history['low'],
                                close=history['close'])
   ```
4. Create a `Layout`.
   ```python
   layout = go.Layout(title=go.layout.Title(text='SPX OHLC'),
                      xaxis_title='Date',
                      yaxis_title='Price',
                      xaxis_rangeslider_visible=False)
   ```
5. Create a `Figure`.
   ```python
   fig = go.Figure(data=[candlestick], layout=layout)
   ```
6. Show the `Figure`.
   ```python
   fig.show()
   ```
   Candlestick charts display the open, high, low, and close prices of the security.

![Candlestick plot of SPX OHLC](https://cdn.quantconnect.com/i/tu/researchhistoryindexonesecuritycandlestickplot.png)

### Line Chart

Follow these steps to plot line charts using built-in methods:

1. Get some historical data.
   ```python
   history = qb.history([spx, vix], datetime(2021, 11, 24), datetime(2021, 12, 8), Resolution.DAILY)
   ```
2. Select the data to plot.
   ```python
   pct_change = history['close'].unstack(0).pct_change().dropna()
   ```
3. Call the `plot` method on the `pandas` object.
   ```python
   pct_change.plot(title="Close Price %Change", figsize=(15, 10))
   ```
4. Show the plot.
   ```python
   plt.show()
   ```
   Line charts display the value of the property you selected in a time series.

![Line chart of indices %chg](https://cdn.quantconnect.com/i/tu/research-env-index-plot.jpg) ![Line chart of indices daily spread](https://cdn.quantconnect.com/i/tu/research-env-index-plot-csharp.png)

## Examples

The following examples demonstrate some common practices for applying the US Indices dataset.

### Example 1: 5-Minute Candlestick Plot

The following example studies the candlestick pattern of the SPX. To study the short term pattern, we consolidate the data into 5 minute bars and plot the 5-minute candlestick plot.

```python
# Import plotly library for plotting.
import plotly.graph_objects as go

# Create a QuantBook
qb = QuantBook()

# Request SPX's historical data.
symbol = qb.add_index("SPX").symbol
history = qb.history(symbol,
    start=qb.time - timedelta(days=182),
    end=qb.time,
    resolution=Resolution.MINUTE)

# Drop level 0 index (Symbol index) from the DataFrame
history = history.droplevel([0])

# Select the required columns to obtain the 5-minute OHLC data.
history = history[["open", "high", "low", "close"]].resample("5T").agg({
    "open": "first",
    "high": "max",
    "low": "min",
    "close": "last"
})

# Crete the Candlestick chart using the 5-minute windows.
candlestick = go.Candlestick(x=history.index,
                             open=history['open'],
                             high=history['high'],
                             low=history['low'],
                             close=history['close'])
# Create a Layout as the plot settings.
layout = go.Layout(title=go.layout.Title(text=f'{symbol} OHLC'),
                   xaxis_title='Date',
                   yaxis_title='Price',
                   xaxis_rangeslider_visible=False)
# Create the Figure.
fig = go.Figure(data=[candlestick], layout=layout)
# Display the plot.
fig.show()
```