--- title: "Core Concepts" description: "Understand the key ideas behind the Time Series API: data points, observations, time series, computed data points and observation types." url: "https://developer-beta.morningstar.com/time-series-api/core-concepts" image: "https://developer-beta.morningstar.com/_og/d/c_Ocean.takumi,title_~Q29yZSBDb25jZXB0cyB8IFRpbWUgU2VyaWVzIEFQSQ,description_~VW5kZXJzdGFuZCB0aGUga2V5IGlkZWFzIGJlaGluZCB0aGUgVGltZSBTZXJpZXMgQVBJOiBkYXRhIHBvaW50cywgb2JzZXJ2YXRpb25zLCB0aW1lIHNlcmllcywgY29tcHV0ZWQgZGF0YSBwb2ludHMgYW5kIG9ic2VydmF0aW9uIHR5cGVzLg,props_eyJ0aGVtZSI6eyJtb2RlIjoibGlnaHQiLCJjb2xvcnMiOnsicHJpbWFyeSI6IiMwMDAwMDAifX19,p_Ii90aW1lLXNlcmllcy1hcGkvY29yZS1jb25jZXB0cyI,s_wq7fVlZ9i-bw4mQP.png" --- - [APIs](https://developer-beta.morningstar.com/apis) - [API Catalog](https://developer-beta.morningstar.com/api-catalog) - [API Assistant MCP Server](https://developer-beta.morningstar.com/api-assistant-mcp) - [Guides](https://developer-beta.morningstar.com/api-guides) - [Trial Access](https://developer-beta.morningstar.com/trial-access) # Time Series API Build Time Series APIs into your digital experience for quick investment and earnings summaries. # Core Concepts [View Markdown](https://developer-beta.morningstar.com/time-series-api/core-concepts.md)[Download Markdown](https://developer-beta.morningstar.com/time-series-api/core-concepts.md) 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](#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. ```text GET /direct-web-services/time-series/v1/{category}/{data-point}/{ids} ``` For example, the following request retrieves the `monthly-return` data point. ```text 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](#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. | Category | Contains | | :------------------ | :------------------------------------------------------------------------------- | | performance | Returns, yields, prices and similar performance measures. | | fund-research | Ratings and analytics, such as the Morningstar Rating and Medalist Rating. | | fund-sustainability | Fund-level sustainability ratings, research and analytics, such as carbon metrics. | | fees-expenses | Fees and expenses, such as accounting, administrator and advisor fees. | | portfolio-holdings | Data points based on portfolio holdings. | | portfolio-analytics | Data points based on portfolio analytics. | | reference | Reference data. | | corporate-actions | Corporate action data. | To find the data point you need, see [Choose a Data Point](https://developer-beta.morningstar.com/time-series-api/choose-a-data-point). ## [Observations](#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`. | Frequency | Observation Cadence | | :-------- | :------------------------------------------------ | | daily | One per trading day. | | weekly | One per week. | | monthly | One per month, dated to the end of the month. | | quarterly | One per quarter, dated to the end of the quarter. | | annually | One per year, dated to the end of the year. | ## [Time Series](#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. | Property | Description | | :---------- | :------------------------------------------------------------------------------- | | identifiers | The identifier of the investment, using the identifier type specified in the request. | | timeSeries | The time series for the investment. It contains the categories and dataPoint names, the data array of observations, and, for computed data points, the performanceType that was used. | | metadata | The lookup details used to find the investment: exchangeCountry, domicile and baseCurrency. | The following response shows one investment with a daily price time series. ```json { "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](https://developer-beta.morningstar.com/time-series-api/work-with-results). ## [Investments and Identifiers](#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](https://developer-beta.morningstar.com/time-series-api/specify-investments). ## [Standard and Computed Data Points](#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. | Data Point | Additional Parameters | | :---------------- | :------------------------------------------------------------------------------- | | return | performanceType, annualDays, preCurrency, requireContinueData | | cumulative-return | performanceType, annualDays, annualized, preCurrency, requireContinueData, stepSize | | rolling-return | performanceType, annualDays, annualized, preCurrency, requireContinueData, stepSize, windowSize | | growth | performanceType, annualDays, initialInvestment, preCurrency, requireContinueData | | price | performanceType | The `growth` and `price` data points are currently in trial. ### [Performance Type](#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. ```text 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](https://developer-beta.morningstar.com/time-series-api/configure-computed-data-points). ## [Univariate and Multivariate Observations](#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`. ```json { "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. ```json { "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](https://developer-beta.morningstar.com/time-series-api/quick-lookup) for the limits. ## [Next Steps](#next-steps) - [Choose a Data Point](https://developer-beta.morningstar.com/time-series-api/choose-a-data-point) to find the data point you need. - [Request Time Series Data](https://developer-beta.morningstar.com/time-series-api/request-time-series-data) to build a request. - [Work with Results](https://developer-beta.morningstar.com/time-series-api/work-with-results) to read the response.