Investment Data#

morningstar_data.direct.get_investment_data(
investments: List[str] | str | Dict[str, Any],
data_points: List[Dict[str, Any]] | str | DataFrame | List[Any] | None = None,
display_name: bool = False,
dry_run: bool | None = False,
time_series_format: TimeSeriesFormat = TimeSeriesFormat.WIDE,
) → DataFrame | DryRunResults#

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) – Default is Wide. Enumeration of md.direct.data_type.TimeSeriesFormat, which can be ‘Wide’, ‘Long’, ‘LongWithoutName’. E.g., md.direct.data_type.TimeSeriesFormat.Long

  • 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
Output:

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
Output:

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
Output:

#

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 with md.direct.data_type.TimeSeriesFormat.long.

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
Output:

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_returns(
investments: List[str] | str | Dict[str, Any],
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 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:

A DataFrame object with returns data.

Return type:

DataFrame

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.

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:

A DataFrame object with excess return data.

Return type:

DataFrame

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.