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.
- 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 (md.direct.data_type.TimeSeriesFormat, optional) –
Specifies the format of the time series data. Default is WIDE. This parameter accepts enumerations from md.direct.data_type.TimeSeriesFormat, which include:
- 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.
- LONG: Data is presented in a long format, where each row represents a single observation for a variable at a point in time.
- 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.

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.

The ‘criteria’ object consists of the following fields:

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"
    }
]

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
=================  ===================================  ================= =========================  =========================

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.