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,
) → DataFrame#

Get data for the given list of investments and data points.

The investments can be provided in one of the following ways:

  • Investment IDs - a list of strings, where each string is the SecId of the investment.

  • List ID - a GUID that represents a saved list id. This method will fetch the contents of the list first, and then get the data points for all investments in that list.

  • Search Criteria ID - a numeric string that represents a saved search criteria. This method will get all investments matching the criteria in the search criteria, and then get data for all provided data points for those investments.

  • Search Criteria Condition - a dictionary describing the detailed search criteria. The dictionary must include universeId and criteria.

The data points can be provided in one of 4 ways:

  • Data Point IDs - a list of dicts, where each dict contains the property datapointId. Data will be returned for this data point with its default parameters. If you would like to override some of those defaults, they can be added to the object. For instance:

    • { “datapointId”: “HP010”} - this would return Monthly Returns for the last 3 years (the default behavior).

    • { “datapointId”: “HP010”, “startDate”: “2015-01-01”, “endDate”: “2017-12-31”} - this would return Monthly Returns for the time period between Jan 1, 2015 and Dec 31, 2017.

  • Data Point Settings - a DataFrame of data points with all defined settings. Each row represents a data point. Each column is a configurable setting. The Dataframe can be retrieved from a data set.

  • Data Set ID - an string that represents a saved data set. The function will get data for all data points in this data set, using the settings defined in the data set.

Parameters:

  • investments (Union, required) –

    An object which can be one of the following:

    • 1. A list of investment codes (list, optional): Use this for an ad hoc approach to selecting investments, rather than using a list or a search. The investment code format is secid;universe or just secid. For example: [“F00000YOOK;FO”,”FOUSA00CFV;FO”] or [“F00000YOOK”,”FOUSA00CFV”].

    • 2. A list ID (str, optional): The unique identifier of the saved investment list from the Workspace module in Morningstar Direct. The format is GUID. For example, “EBE416A3-03E0-4215-9B83-8D098D2A9C0D”.

    • 3. Search Criteria ID (str, optional): The unique identifier of a saved search criteria from Morningstar Direct. The id string is numeric. For example, “9009”.

    • 4. Search Criteria Condition (dict, optional): The detailed search criteria. The dictionary must include the keys universeId and criteria. 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"}]}

  • data_points (Union, optional) – An object which can be one of the following, if no value is provided and

  • ID (there is a list ID or search criteria) –

    • 1. Data point IDs (list, optional): A list of unique identifiers for data points. The format is an array of data points with (optionally) associated settings. For example:

      [
    {
        "datapointId": "OS01W"
    },
    {
        "datapointId": "HP010",
        "isTsdp": True,
        "currency": "CNY",
        "startDate": "2021-03-01",
        "endDate": "2021-08-31"
    }
]

    • 2. Data Set ID (str, optional): The unique identifier of a Morningstar data set or user created data set saved in Morningstar Direct. The id string is numeric. For example: “6102286”.

      1. Data point Settings (DataFrame, optional): A DataFrame of data points and their associated setting values.

  • default. (the API will get the corresponding bound dataset by) –

    • 1. Data point IDs (list, optional): A list of unique identifiers for data points. The format is an array of data points with (optionally) associated settings. For example:

      [
    {
        "datapointId": "OS01W"
    },
    {
        "datapointId": "HP010",
        "isTsdp": True,
        "currency": "CNY",
        "startDate": "2021-03-01",
        "endDate": "2021-08-31"
    }
]

    • 2. Data Set ID (str, optional): The unique identifier of a Morningstar data set or user created data set saved in Morningstar Direct. The id string is numeric. For example: “6102286”.

      1. Data point Settings (DataFrame, optional): A DataFrame of data points and their associated setting values.

  • display_name – bool: This argument determines if the investment_data should have displayName as the column names for datasets

Returns:

A DataFrame object with investment data. The DataFrame columns include data point name that user input in parameter data_points.

Return type:

DataFrame

Examples:

Get investment data based on investment list id and data point list id.

import morningstar_data as md

df = md.direct.get_investment_data(
    investments=["F0AUS05U7H", "F000010NJ5"],
    data_points=[
        {"datapointId": "OS01W", "isTsdp": False},
        {"datapointId": "LS05M", "isTsdp": False},
    ],
)
df
Output:

Id

Name

Base Currency

Base Currency - display text

F0AUS05U7H

Walter Scott Global Equity

AUD

Australian Dollar

F000010NJ5

Vontobel Emerging Markets Eq U1 USD

USD

US Dollar

Get investment data based on investment list id and datapoint id list.

import morningstar_data as md

df = md.direct.get_investment_data(
    investments="a727113a-9557-4378-924f-5d2ba553f687",
    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 based on search criteria id and datapoint id list.

import morningstar_data as md

df = md.direct.get_investment_data(
    investments="4216254", 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 based on search criteria id and data point id list.

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
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) –

    Can be provided in one of the following ways:

    • Investment IDs (list, optional): An array of investment codes. Use this for an ad hoc approach to selecting investments, rather than using a list or a search. The investment code format is secid;universe or just secid. For example: [“F00000YOOK;FO”,”FOUSA00CFV;FO”] or [“F00000YOOK”,”FOUSA00CFV”].

    • List ID (str, optional): The unique identifier of the saved investment list from the Workspace module in Morningstar Direct. The format is GUID. For example, “EBE416A3-03E0-4215-9B83-8D098D2A9C0D”.

    • Search Criteria ID (str, optional): The unique identifier of a saved search criteria from Morningstar Direct. The id string is numeric. For example, “9009”.

    • Search Criteria Condition (dict, optional): The detailed search criteria. The dictionary must include the keys universeId and criteria. 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"}]}

  • start_date (str) – The beginning date of a data range for retrieving data. The format is YYYY-MM-DD. For example, “2020-01-01”.

  • end_date (str, optional) – The end date of data range for retrieving data. If no value is provided for end_date, current date will be used. The format is YYYY-MM-DD. For example, “2020-01-01”.

  • freq (Frequency) –

    Return frequency, the possible enum values are:

    • daily

    • weekly

    • monthly

    • quarterly

    • yearly

  • currency (str, optional) – Three character code for the desired currency of returns.

Returns:

The DataFrame columns include Name and the investment name for each investment id in the investments argument.

Return type:

DataFrame

Examples

Get monthly return.

import morningstar_data as md


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

Name Date

(LF) FoF Bal Blnd US Priv Banking

(LF) High Yield A List Priv Banking

2020-10-31

-2.121865

-0.686248

2020-11-30

6.337255

5.682299

2020-12-31

1.464777

3.011518

…
Errors:

AccessDeniedError: Raised when user lacks authentication.

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

ForbiddenError: Triggered when user lacks permission to access a resource.

InternalServerError: Raised when the server encounters an error it does not know how to handle.

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) –

    Can be provided in one of the following ways:

    • Investment IDs (list, optional): An array of investment codes. Use this for an ad hoc approach to selecting investments, rather than using a list or a search. The investment code format is secid;universe or just secid. For example: [‘F00000YOOK;FO’,’FOUSA00CFV;FO’] or [‘F00000YOOK’,’FOUSA00CFV’].

    • List ID (str, optional): The unique identifier of the saved investment list from the Workspace module in Morningstar Direct. The format is GUID. For example, ‘EBE416A3-03E0-4215-9B83-8D098D2A9C0D’.

    • Search Criteria ID (str, optional): The unique identifier of a saved search criteria from Morningstar Direct. The id string is numeric. For example, “9009”.

    • Search Criteria Condition (dict, optional): The detailed search criteria. The dictionary must include the keys universeId and criteria. 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"}]}

  • benchmark_sec_id (str) – The SecId of the security to use as the benchmark.

  • start_date (str) – The beginning date of a data range for retrieving data. The format is YYYY-MM-DD. For example, “2020-01-01”.

  • end_date (str, optional) – The end date of data range for retrieving data. The format is YYYY-MM-DD. For example, “2020-01-01”.

  • freq (Frequency) –

    Return frequency, the possible enum values are:

    • daily

    • weekly

    • monthly

    • quarterly

    • yearly

  • currency (str, optional) – Three character code for the desired currency of returns.

Returns:

A DataFrame object with excess return data. The DataFrame columns include Name and the investment name for each investment id in the investments argument.

Return type:

DataFrame

Examples

Get monthly return.

import morningstar_data as md

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

Name Date

(LF) FoF Bal Blnd US Priv Banking

(LF) High Yield A List Priv Banking

2020-01-01

-1150.623143

-1154.382165

2020-01-02

-1146.064892

-1149.928106

…
Errors:

AccessDeniedError: Raised when user lacks authentication.

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

ForbiddenError: Triggered when user lacks permission to access a resource.

InternalServerError: Raised when the server encounters an error it does not know how to handle.

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.