Core Concepts

The Time Series API returns historical data for investments. Each type of data is called a data point, and each data point has its own endpoint. This page explains the terms used throughout the guide so that requests and responses are easier to read.

Data Points

A data point is a named measure that the API can return over time, such as daily-price, monthly-return or morningstar-rating-overall. The API has a dedicated endpoint for each data point, and each request retrieves one data point for up to 25 investments. Some data points are available under more than one category, in which case each category has its own endpoint.

Every endpoint follows the same pattern, with the data point name in the path.

GET /direct-web-services/time-series/v1/{category}/{data-point}/{ids}

For example, the following request retrieves the monthly-return data point.

GET /direct-web-services/time-series/v1/performance/monthly-return/0P00000CSY

The {ids} path parameter holds the investments you are requesting, and everything else, such as the time range and currency, is passed as query parameters.

Categories

Data points are organized into categories. The category forms part of the endpoint path, and it is returned in the categories property of each time series.

To find the data point you need, see Choose a Data Point.

Observations

An observation is a single recorded measurement at a point in time. It consists of a date and one or more values.

The frequency parameter controls the interval between observations. The default is daily.

Time Series

A time series is the chronological sequence of observations for one investment and one data point.

Because each request retrieves a single data point, the response contains one time series for each investment. A request for three investments returns three time series, one under each investment in the investments array.

Each investment object in the response has three properties.

The following response shows one investment with a daily price time series.

{
  "investments": [
    {
      "identifiers": {
        "performanceId": "0P00000CSY"
      },
      "timeSeries": {
        "categories": ["performance"],
        "dataPoint": "daily-price",
        "data": [
          { "date": "2025-01-02", "value": 0.71234 },
          { "date": "2025-01-03", "value": 0.72108 }
        ]
      },
      "metadata": {
        "exchangeCountry": "USA",
        "domicile": "USA",
        "baseCurrency": "USD"
      }
    }
  ]
}

The response also has a top-level metadata object, which includes the requestId, the time of the response, and warnings about any identifiers that returned no results. See Work with Results.

Investments and Identifiers

Investments are identified by the values in the ids path parameter. The API accepts the following identifier types.

• Morningstar Performance ID (default)
• Morningstar Security ID
• Morningstar IDs (MSID)
• ISIN
• CUSIP
• Trading symbol
• Category ID

When an identifier matches more than one investment, the API uses lookup context to choose between them. The lookup context is made up of exchangeCountry, domicile and baseCurrency, and it is returned in the metadata of each investment so you can see which one was applied. The defaults are USA for exchangeCountry and domicile, and USD for baseCurrency.

For how to set these in a request, see Specify Investments.

Standard and Computed Data Points

Data points are either standard or computed. The difference affects how the API processes the request and which parameters you can use.

Standard data points return values from stored data. Only the general request parameters, such as the time range and currency, apply. Most data points are standard, including daily-price, monthly-return and daily-ohlcv.

Computed data points calculate their values when you make the request, so they accept extra parameters that control the calculation. The following computed data points are available.

The growth and price data points are currently in trial.

Performance Type

The performanceType parameter sets which performance stream a computed data point uses. The values are total, market and gross, and the default is total.

You can pass up to two values. The first is the preferred type, and the second is a fallback that is used if the first returns no data. If you pass one value, no fallback is attempted. The response returns the performanceType that was applied, so you can always see which stream was used.

The following request calculates 12-month rolling returns using total performance.

GET /direct-web-services/time-series/v1/performance/rolling-return/0P00000CSY
  ?startDate=2020-01-01
  &endDate=2025-01-01
  &performanceType=total
  &windowSize=12
  &frequency=monthly

For details on each parameter, see Configure Computed Data Points.

Univariate and Multivariate Observations

The shape of the data array depends on whether the data point returns univariate or multivariate observations.

Univariate observations contain a date and a single value. Almost all data points return univariate observations, for example daily-price, monthly-return and rolling-return.

{
  "dataPoint": "daily-price",
  "data": [
    { "date": "2025-01-02", "value": 0.71234 },
    { "date": "2025-01-03", "value": 0.72108 }
  ]
}

Multivariate observations contain a date and several values. Currently only daily-ohlcv returns multivariate observations, with separate fields for the open, high, low and closing price and the volume.

{
  "dataPoint": "daily-ohlcv",
  "data": [
    {
      "date": "2025-01-02",
      "dailyOpenPrice": 5.17,
      "dailyHighPrice": 5.21,
      "dailyLowPrice": 5.14,
      "dailyClosingPrice": 5.19,
      "dailyVolume": 130918
    }
  ]
}

The data point determines the observation type, not a request parameter. Use the dataPoint value in each time series to decide how to parse the data array.

Multivariate data points have some different request rules. They have a shorter maximum lookback than univariate data points, and sinceInception isn't supported. See Quick Lookup for the limits.

Next Steps

• Choose a Data Point to find the data point you need.
• Request Time Series Data to build a request.
• Work with Results to read the response.