Investment Data#

Retrieve data for the specified investments and data points.

Parameters:

investments (Union, required) –
Defines the investments to fetch. Input can be:
- Investment IDs (list, optional): Investment identifiers, in the format of SecId;Universe or just SecId. E.g., [“F00000YOOK;FO”,”FOUSA00CFV;FO”] or [“F00000YOOK”,”FOUSA00CFV”]. Use the investments function to discover identifiers.
- InvestmentIdentifiers (list, optional): A list of InvestmentIdentifier objects, allowing users to specify investments using standard identifiers such as ISIN, CUSIP, and/or ticker symbol instead of Morningstar SecIds. Introduced in version 1.11.0.
  - Multiple Matches: If multiple valid matches exist for a single InvestmentIdentifier, results will be prioritized according to the security matching logic. The highest ranked security will be used.
  - Request Limit: Supports up to 500 InvestmentIdentifier objects per request.
- Investment List ID (str, optional): Saved investment list in Morningstar Direct. Currently, this function does not support lists that combine investments and user-created portfolios. Use the get_investment_lists function to discover saved lists.
- Search Criteria ID (str, optional): Saved search criteria in Morningstar Direct. Use the get_search_criteria function to discover saved search criteria.
- Search Criteria Condition (dict, optional): Search criteria definition. See details in the Reference section below or use the get_search_criteria_conditions function to discover the definition of a saved search criteria.
data_points (Union, optional) –
Defines the data points to fetch. If not provided and investments are specified with a list ID or search criteria ID, the corresponding bound dataset will be used.
- Data Point IDs (List[Dict], optional): A list of dictionaries, each defining a data point and its (optional) associated settings.
- Data Set ID (str, optional): Morningstar data set or user-created data set saved in Morningstar Direct. Use the get_data_sets or get_morningstar_data_sets functions to discover saved data sets.
- Data Point Settings (DataFrame, optional): A DataFrame of data point identifiers and their associated settings. Use the get_data_set_details function to discover data point settings from a saved data set.
display_name (bool, optional) – When true, the returned column names will match display names saved in the data set. Default is false.
time_series_format (direct.TimeSeriesFormat, optional) –
Specifies the format of the time series data. Default is WIDE. Accepted values are:
- TimeSeriesFormat.WIDE: Data is presented in a wide format, where each row contains a different investment with values for each point in time in a different column.
- TimeSeriesFormat.LONG: Data is presented in a long format, where each row represents a single observation for a variable at a point in time.
- TimeSeriesFormat.LONG_WITHOUT_NAME: Similar to the long format but excludes the ‘Name’ column.
dry_run (bool, optional) – When True, the query will not be executed. Instead, a DryRunResults object will be returned with details about the query’s impact on daily cell limit usage.
unmatched_investment_behavior (WarningBehavior, optional) –
Determines behavior when any of the input investments can’t be found.
- WarningBehavior.FAIL: A ResourceNotFoundError is raised if any of the investments can’t be found.
- WarningBehavior.WARNING (default): A warning is displayed listing any investments that were not found. A ResourceNotFoundError is raised if all investments were not found.
- WarningBehavior.IGNORE: No warning is displayed if any investments were not found. A ResourceNotFoundError is raised if all investments were not found.

Returns:

There are two return types:

DataFrame: A DataFrame object with investment data
DryRunResults: Is returned if dry_run=True is passed
- estimated_cells_used: Number of cells by this query
- daily_cells_remaining_before: How many cells are remaining in your daily cell limit before running this query
- daily_cells_remaining_after: How many cells would be remaining in your daily cell limit after running this query
- daily_cell_limit: Your total daily cell limit

Reference:

Constructing a Search Criteria Condition dictionary:

For example:

SEARCH_CRITERIA_CONDITION = {
        "universeId": "cz",
        "subUniverseId": "",
        "subUniverseName": "",
        "securityStatus": "activeonly",
        "useDefinedPrimary": False,
        "criteria": [
            {"relation": "", "field": "HU338", "operator": "=", "value": "1"},
            {"relation": "AND", "field": "HU863", "operator": "=", "value": "1"}
        ]
    }

universeId (string, required): Universe code (e.g., “FO”). Use the get_investment_universes function to explore available values or download the reference file.
subUniverseId (string, optional): Sub-universe code, if applicable. See the refererece file above for available values.
subUniverseName (string, optional): Name of sub-universe, if applicable. See the refererece file above for available values.
securityStatus (string, optional): Security status, can be ‘activeonly’ or ‘activeinactive’.
useDefinedPrimary (Boolean, optional): If set to true, Morningstar Direct user-defined settings will be used.
criteria (List[Dict[]], required): Custom search conditions. Dictionary fields described below.
- field (string): Data point identifier
- value (string): Value to compare against the data point.
- criteria (List[Dict[]]): A nested list of additional custom search conditions.
- relation (string, required): Boolean condition used when joining with the previous condition. Accepts an empty string (for the first condition, as no previous condition exists to join with), ‘Or’, or ‘And’.
- operator (string): Operator used to compare field value to value. Possible operators include ‘=’, ‘!=’, ‘<’, ‘>’, ‘<=’, ‘>=’, ‘like’ (data contains value), and ‘not like’ (data does not contain value).
  
  For example:
```
[
    {
        "field": "eb919bcc-c097-4fe3-898c-470d8b89dde1"
        "operator": "="
        "relation": ""
        "value": "122"
    },
    {
        "criteria": [
            {...Condition1 },
            {...Condition2 },
            {...Condition3 },
        ],
        "relation": "And"
    },
    {
        "field": "LS466"
        "operator": "="
        "relation": "Or"
        "value": "FH"
    }
]
```

Usage Examples#

Get investment data for the given investments and data points.

import morningstar_data as md

df = md.direct.get_investment_data(
    investments=["F0AUS05U7H", "F000010NJ5"],
    data_points=[
        {"datapointId": "OS01W"}, # Name
        {"datapointId": "LS05M"}, # Base Currency
        {
            "datapointId": "HP010", # Monthly Return
            "isTsdp": True,
            "currency": "CNY",
            "startDate": "2021-03-01",
            "endDate": "2021-08-31",
        },
    ],
)
df

Output:

Id	Name	Base Currency	Monthly Return 2021-03-31	Monthly Return 2021-04-30
F0AUS05U7H	Walter Scott Global Equity	Australian Dollar	3.726094	3.078352
F000010NJ5	Vontobel Emerging Markets Eq U1 USD	US Dollar	-0.417526	-0.376890

Get investment data for a saved investment list and data points.

import morningstar_data as md

df = md.direct.get_investment_data(
    investments="a727113a-9557-4378-924f-5d2ba553f687", # Replace with a valid List ID
    data_points=[{"datapointId": "HS793", "isTsdp": True}],
)
df

Id	Name	Daily Return Index 2021-09-23	Daily Return Index 2021-09-24	Daily Return Index 2021-09-25
FOUSA00DFS;FO	BlackRock Global Allocation Inv A	129.92672	129.56781	129.56781

Get investment data for a saved search criteria and data points.

import morningstar_data as md

df = md.direct.get_investment_data(
    investments="4216254", # Replace with a valid Search Criteria ID
    data_points=[{"datapointId": "12", "isTsdp": True}]
)
df

Id	Name	Beta 2018-10-01 to 2021-09-30
FOUSA06JNH;FO	DWS RREEF Real Assets A	0.654343

Get investment data for a custom search criteria and data points.

import morningstar_data as md

SEARCH_CRITERIA_CONDITION = {
    "universeId": "cz",
    "subUniverseId": "",
    "subUniverseName": "",
    "securityStatus": "activeonly",
    "useDefinedPrimary": False,
    "criteria": [
        {"relation": "", "field": "HU338", "operator": "=", "value": "1"},
        {"relation": "AND", "field": "HU863", "operator": "=", "value": "1"},
    ],
}

df = md.direct.get_investment_data(
    investments=SEARCH_CRITERIA_CONDITION,
    data_points=[{"datapointId": "HS793", "isTsdp": True}],
)
df

#	Id	Name	Daily Return Index 2022-02-18	…	Daily Return Index 2022-03-17
0	FOUSA06UOR;CZ	Columbia Trust Stable Government Fund	None	…	None
1	FOUSA06UWL;CZ	Columbia Trust Stable Income Fund	88.8333	…	90.7781

Get investment data for the given investments and data points in the long format.

import morningstar_data as md

df = md.direct.get_investment_data(
    investments=["F0AUS05U7H", "F000010NJ5"],
    data_points=[
        {"datapointId": "OS01W"}, # Name
        {"datapointId": "LS05M"}, # Base Currency
        {
            "datapointId": "HP010", # Monthly Return
            "isTsdp": True,
            "currency": "CNY",
            "startDate": "2021-03-01",
            "endDate": "2021-08-31",
        },
    ],
    time_series_format=md.direct.data_type.TimeSeriesFormat.LONG
)
df

Id	Name	Base Currency	Date	Monthly Return
F0AUS05U7H	Walter Scott Global Equity	Australian Dollar	2021-04-30	3.726094
F0AUS05U7H	Walter Scott Global Equity	Australian Dollar	2021-05-31	3.078352
F0AUS05U7H	Walter Scott Global Equity	Australian Dollar	2021-06-30	3.078352
F000010NJ5	Vontobel Emerging Markets Eq U1 USD	US Dollar	2021-04-30	-0.417526
F000010NJ5	Vontobel Emerging Markets Eq U1 USD	US Dollar	2021-05-31	-0.376890
F000010NJ5	Vontobel Emerging Markets Eq U1 USD	US Dollar	2021-06-30	3.078352

Using Ticker to retrieve data for Apple (AAPL).

 import morningstar_data as md
 from morningstar_data.direct import InvestmentIdentifier

 # Define the data point IDs to retrieve
 data_point_ids = [
     {"datapointId": "LS05M"}, # Base Currency
     {"datapointId": "LS01Z"}, # Exchange by Name
     {"datapointId": "OS00F"},  # Inception Date
     {"datapointId": "LS017"}   # Domicile
 ]

# Initialize an InvestmentIdentifier object for the ticker symbol
investments = [InvestmentIdentifier(ticker="AAPL")]

# Retrieve investment data using the defined ticker and data points
df = md.direct.get_investment_data(investments, data_point_ids)

df

Id	Name	Base Currency	Exchange	Inception Date	Domicile
0P000000GY	Apple Inc	US Dollar	Nasdaq - All Markets	1980-12-12	United States

Using Ticker and Currency to retrieve data for Apple (AAPL).

import morningstar_data as md
from morningstar_data.direct import InvestmentIdentifier

# Define the data point IDs to retrieve
data_point_ids = [
    {"datapointId": "LS05M"}, # Base Currency
    {"datapointId": "LS01Z"}, # Exchange by Name
    {"datapointId": "OS00F"},  # Inception Date
    {"datapointId": "LS017"}   # Domicile
]

# Example: Using Ticker and Base Currency
investments = [InvestmentIdentifier(ticker="AAPL", base_currency="Euro")]

# Retrieve the data via ticker
df = md.direct.get_investment_data(investments, data_point_ids)

df

Id	Name	Base Currency	Exchange	Inception Date	Domicile
0P0000EEPX	Apple Inc	Euro	Wiener Boerse AG	2017-05-23	United States

Retrieving Investment Data Using Ticker and Exchange.

import morningstar_data as md
from morningstar_data.direct import InvestmentIdentifier

# Define the data point IDs to retrieve
data_point_ids = [
    {"datapointId": "LS05M"}, # Base Currency
    {"datapointId": "LS01Z"}, # Exchange by Name
    {"datapointId": "OS00F"},  # Inception Date
    {"datapointId": "LS017"}   # Domicile
]

# Example: Using Ticker and Exchange
investments = [InvestmentIdentifier(ticker="MSFT", exchange="Toronto Stock Exchange")]

# Retrieve the data via Ticker and Exchange
df = md.direct.get_investment_data(investments, data_point_ids)

df

Id	Name	Base Currency	Exchange	Inception Date	Domicile
0P0001NHUC	Microsoft Corp Canadian Depository Receipt	Canadian Dollar	Toronto Stock Exchange	2021-10-05	United States

Retrieving Investment Data Using ISINs and CUSIPs.

import morningstar_data as md
from morningstar_data.direct import InvestmentIdentifier

# Defining Datapoints
data_point_ids = [
    {"datapointId": "LS05M"},  # Base Currency
    {"datapointId": "LS01Z"},  # Exchange by Name
    {"datapointId": "LF035"},  # Global Broad Category Group
    {"datapointId": "ZZ006"},  # Annual Expense Ratio
]

# Example: Using ISINs and CUSIPs
investments = [
    InvestmentIdentifier(isin="US6176971074"),  # ISIN for the Morningstar US Equity Fund
    InvestmentIdentifier(cusip="453320103"),    # CUSIP for the Income Fund of America
]

# Retrieve the data via ISIN and CUSIP
df = md.direct.get_investment_data(investments, data_point_ids)

df

#	Id	Name	Base Currency	Exchange	Global Broad Category Group	Annual Report Adjusted Expense Ratio
1	F00000YOOK	Morningstar US Equity	US Dollar	Nasdaq - All Markets	Equity	0.84
2	FOUSA00D6E	American Funds Income Fund of Amer A	US Dollar	Nasdaq - All Markets	Allocation	0.58

Bulk Processing via Identifier Lists.

import morningstar_data as md
from morningstar_data.direct import InvestmentIdentifier
import pandas as pd

# Defining Data Points
data_point_ids = [
    {"datapointId": "LS05M"},  # Base Currency
    {"datapointId": "LS01Z"},  # Exchange by Name
    {"datapointId": "LF035"},  # Global Broad Category Group
    {"datapointId": "ZZ006"},  # Annual Expense Ratio
]

# Read the list of ISINs from securities.csv
df_securities = pd.read_csv("securities.csv")

# Extract the list of ISINs from the DataFrame
isin_list = df_securities['ISIN'].tolist()

# Create InvestmentIdentifier objects using the ISINs list
investments_isins = [InvestmentIdentifier(isin=isin) for isin in isin_list]

# Retrieve the securities and the associated data_point_ids simply using ISINs
df = md.direct.get_investment_data(
    investments=investments_isins,
    data_points=data_point_ids
)

df

#	Id	Name	Base Currency	Exchange	Global Broad Category Group	Annual Report Adjusted Expense Ratio
1	FOUSA00K3V	AB Concentrated Growth Advisor	US Dollar	Nasdaq - All Markets	Equity	0.75
2	FOUSA00CAQ	AB Growth A	US Dollar	Nasdaq - All Markets	Equity	1.09
3	FOUSA00B92	AB Large Cap Growth A	US Dollar	Nasdaq - All Markets	Equity	0.81
4	F00000YDG4	AB Sustainable US Thematic Advisor	US Dollar	Nasdaq - All Markets	Equity	0.65
5	FOUSA00LBE	abrdn US Sustainable Leaders A	US Dollar	Nasdaq - All Markets	Equity	1.19

Note

InvestmentSearchWarning: This warning is raised when the get_investment_data function is unable to find investments for all provided fields in InvestmentIdentifier objects. If you encounter this warning, review your identifiers to ensure they are valid and correctly specified.

morningstar_data.direct.get_excess_returns( investments: List | str | Dict[str, Any], benchmark_sec_id: str, start_date: str = '2020-01-01', end_date: str | None = None, freq: Frequency | str = Frequency.monthly, currency: str | None = None, ) → DataFrame#

A shortcut function to fetch excess return data for the specified investments.

Parameters:

investments (Union, required) –
Defines the investments to fetch. Input can be:
- Investment IDs (list, optional): Investment identifiers, in the format of SecId;Universe or just SecId. E.g., [“F00000YOOK;FO”,”FOUSA00CFV;FO”] or [“F00000YOOK”,”FOUSA00CFV”]. Use the investments function to discover identifiers.
- Investment List ID (str, optional): Saved investment list in Morningstar Direct. Use the get_investment_lists function to discover saved lists.
- Search Criteria ID (str, optional): Saved search criteria in Morningstar Direct. Use the get_search_criteria function to discover saved search criteria.
- Search Criteria Condition (dict, optional): Search criteria definition. See details in the Reference section of get_investment_data or use the get_search_criteria_conditions function to discover the definition of a saved search criteria.
benchmark_sec_id (str) –
SecId of the security to use as the benchmark. Use the investments function to discover identifiers.
start_date (str) – Start date of a date range for retrieving data. The format is YYYY-MM-DD, e.g., “2020-01-01”.
end_date (str, optional) – End date of a date range for retrieving data. If no value is provided for end_date, current date will be used. The format is YYYY-MM-DD, e.g., “2020-01-01”.
freq (md.direct.data_type.Frequency) – Enumeration of type md.direct.data_type.Frequency, which can be ‘daily’, ‘weekly’, ‘monthly’, ‘quarterly’, or ‘yearly’. E.g., md.direct.data_type.Frequency.monthly
currency (str, optional) – Three character code for the desired currency of returns, e.g., “USD”. Use the currency_codes function to discover possible values.

Returns:

DataFrame: A DataFrame object with excess return data.

Examples:

Get monthly excess returns.

import morningstar_data as md

df = md.direct.get_excess_returns(
    investments=["F00000VKPI", "F000014B1Y"],
    benchmark_sec_id="F00000PLYW",
    freq=md.direct.data_type.Frequency.daily
)
df

Output:

ID	Date	Monthly Return
F00000VKPI	2020-10-31	-2.121865
F00000VKPI	2020-11-30	6.337255
F00000VKPI	2020-12-31	1.464777
…	…	…

Errors:

AccessDeniedError: Raised when the user is not authenticated.

BadRequestError: Raised when the user does not provide a properly formatted request.

ForbiddenError: Raised when the user does not have permission to access the requested resource.

InternalServerError: Raised when the server encounters an unhandled error.

NetworkExceptionError: Raised when the request fails to reach the server due to a network error.

ResourceNotFoundError: Raised when the requested resource does not exist in Direct.

A shortcut function to fetch return data for the specified investments.

Parameters:

investments (Union, required) –
Defines the investments to fetch. Input can be:
- Investment IDs (list, optional): Investment identifiers, in the format of SecId;Universe or just SecId. E.g., [“F00000YOOK;FO”,”FOUSA00CFV;FO”] or [“F00000YOOK”,”FOUSA00CFV”]. Use the investments function to discover identifiers.
- Investment List ID (str, optional): Saved investment list in Morningstar Direct. Use the get_investment_lists function to discover saved lists.
- Search Criteria ID (str, optional): Saved search criteria in Morningstar Direct. Use the get_search_criteria function to discover saved search criteria.
- Search Criteria Condition (dict, optional): Search criteria definition. See details in the Reference section of get_investment_data or use the get_search_criteria_conditions function to discover the definition of a saved search criteria.
start_date (str) – Start date of a date range for retrieving data. The format is YYYY-MM-DD, e.g., “2020-01-01”.
end_date (str, optional) – End date of a date range for retrieving data. If no value is provided for end_date, current date will be used. The format is YYYY-MM-DD, e.g., “2020-01-01”.
freq (md.direct.data_type.Frequency) – Enumeration of type md.direct.data_type.Frequency, which can be ‘daily’, ‘weekly’, ‘monthly’, ‘quarterly’, or ‘yearly’. E.g., md.direct.data_type.Frequency.monthly
currency (str, optional) –
Three character code for the desired currency of returns, e.g., “USD”. Use the currency_codes function to discover possible values.

Returns:

DataFrame: A DataFrame object with returns data.

Examples:

Get monthly returns.

import morningstar_data as md


df = md.direct.get_returns(
    investments=["F00000VKPI", "F000014B1Y"], start_date="2020-10-01", freq=md.direct.data_type.Frequency.monthly
)
df

Output:

ID	Date	Monthly Return
F00000VKPI	2020-10-31	-2.121865
F00000VKPI	2020-11-30	6.337255
F00000VKPI	2020-12-31	1.464777
…	…	…

Errors:

AccessDeniedError: Raised when the user is not properly authenticated.

BadRequestError: Raised when the user does not provide a properly formatted request.

ForbiddenError: Raised when the user lacks permission to access a resource.

InternalServerError: Raised when the server encounters an unhandled error.

NetworkExceptionError: Raised when the request fails to reach the server due to a network error.

ResourceNotFoundError: Raised when the requested resource does not exist in Direct.