Holdings Data#

morningstar_data.direct.get_holding_dates(
investment_ids: List[str],
) → DataFrame#

Returns all dates with available holdings data for the given investment.

Parameters:

investment_ids (list) – A list of investment IDs. The investment ID format is SecId;Universe or just SecId. For example: [“F00000YOOK;FO”,”FOUSA00CFV;FO”] or [“F00000YOOK”,”FOUSA00CFV”].

Returns:

DataFrame: A DataFrame object with portfolio date data. DataFrame columns include:

  • secId

  • date

Examples:

Retrieve portfolio dates for investment “FOUSA00KZH”.

import morningstar_data as md

df = md.direct.get_holding_dates(investment_ids=["FOUSA06JNH"])
df
Output:

secId

date

FOUSA06JNH

2021-08-31

FOUSA06JNH

2021-07-31

…
morningstar_data.direct.get_holdings(
investments: List[str] | str | Dict[str, Any] | List[InvestmentIdentifier] | None = None,
date: str | List[str] | None = None,
start_date: str | None = None,
end_date: str | None = None,
investment_ids: List[str] | None = None,
data_points: List[Dict[str, Any]] | DataFrame | None = None,
frequency: Frequency = Frequency.monthly,
holdings_view: int | HoldingsView = HoldingsView.FULL,
suppression_client_id: str | None = None,
enrichment_type: EnrichmentType = EnrichmentType.POINT_IN_TIME,
delta_start_time: str | None = None,
delta_include_unchanged_data: bool | None = None,
dry_run: bool | None = False,
preview: bool | None = False,
) → DataFrame | DryRunResults#

Returns base level holdings details for the specified investments. Note that if none of the date parameters are provided, the function uses the latest portfolio date by default.

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.

    • 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.

      • 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.

  • date (str, list[str], optional) – The portfolio date for which to retrieve data. The format is YYYY-MM-DD. For example, “2020-01-01”. If a date is provided, then the start_date and end_date parameters are ignored. Can also be a list of dates. The list can contain a maximum of 20 dates. An exception is thrown if start_date or end_date is provided along with date.

  • start_date (str, optional) – The start date for retrieving data. The format is YYYY-MM-DD. For example, “2020-01-01”. An exception is thrown if date is provided along with start_date.

  • end_date (str, optional) – The end date 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”. An exception is thrown if date is provided along with end_date.

  • investment_ids (list) – DEPRECATED, A list of investment IDs. The investment ID format is SecId;Universe or just SecId. For example: [“F00000YOOK;FO”,”FOUSA00CFV;FO”] or [“F00000YOOK”,”FOUSA00CFV”].

  • data_points (Union, optional) –

    Defines the data points to fetch. If no data points are provided, a default list of data points with predefined aliases are returned, below are the list of default data points and associated aliases.

    • Data Point IDs (List[Dict], optional): A list of dictionaries, each defining a data point and its (optional) associated settings. If an alias is provided in the data point setting, it will be used as the column name in the returned DataFrame. Otherwise, the data point ID will be used as the column name.

    • 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.

  • frequency (md.direct.data_type.Frequency, optional) –

    Frequency at which data point values are retrieved. The default is Frequency.monthly.

    • daily: Portfolio holdings data reported daily.

    • monthly: Portfolio holdings data reported on or close to the month-end calendar dates.

  • holdings_view (Union, optional) –

    Specifies the level of detail returned for portfolio holdings. This can be an integer or md.direct.data_type.HoldingsView. The default is HoldingsView.FULL.

    • Integer Value N: Returns only top N holdings for each portfolio.

    • FULL: Returns all available holdings for the portfolio on requested dates.

    • BEST_AVAILABLE: Returns the most complete holdings data available for each requested date.

  • suppression_client_id (str, optional) – If you have a privileged access to suppressed portfolios and would like to apply it, provide your Client ID.

  • enrichment_type (md.direct.data_type.EnrichmentType, optional) –

    Specifies the enrichment type of the data returned. The default is EnrichmentType.POINT_IN_TIME.

    • LATEST_AVAILABLE: Uses the most current data at feed generation time.

    • POINT_IN_TIME: Matches the data to each portfolio’s effective date.

    • LATEST_MONTH_END: Uses the latest available month-end data at request time.

  • 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.

  • preview (bool, optional) – Defaults to False. Setting to True allows access to data points outside of your current subscription, but limits the output to 25 rows.

Returns:

There are two return types:

DataFrame: A DataFrame object with holdings data. DataFrame columns include:

  • masterPortfolioId

  • investmentId

  • portfolioCurrency

  • portfolioDate

  • holdingsView

  • holdingStorageId

  • secId

  • name

  • defaultHoldingTypeCode

  • isin

  • cusip

  • weight

  • shares

  • marketValue

  • sharesChanged

  • ticker

  • currency

  • detailHoldingType

  • Other columns based on requested data points (column name will be the alias if provided, otherwise the data point ID)

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

Raises:

ValueErrorException – Raised when input parameters are invalid.

Examples:

Retrieve holdings for investment “FOUSA00KZH” on “2020-12-31”.

import morningstar_data as md

df = md.direct.get_holdings(investments=["FOUSA00KZH"], date="2020-12-31")
df
Output:

masterPortfolioId

investmentId

…

currency

detailHoldingType

6079

FOUSA00KZH

…

US Dollar

EQUITY

6079

FOUSA00KZH

…

US Dollar

EQUITY

…
morningstar_data.direct.get_lookthrough_holdings(
investments: List[str] | str | Dict[str, Any] | List[InvestmentIdentifier] | None = None,
date: str | List[str] | None = None,
start_date: str | None = None,
end_date: str | None = None,
data_points: List[Dict[str, Any]] | str | DataFrame | List[Any] | None = None,
frequency: Frequency = Frequency.monthly,
holdings_view: int | HoldingsView = HoldingsView.FULL,
suppression_client_id: str | None = None,
enrichment_type: EnrichmentType = EnrichmentType.POINT_IN_TIME,
delta_start_time: str | None = None,
delta_include_unchanged_data: bool | None = None,
dry_run: bool | None = False,
preview: bool | None = False,
) → DataFrame | DryRunResults#

Returns holdings details and expands all holdings into their nested underlying securities. Note that if none of the date parameters are provided, the function uses latest portfolio date by default.

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.

    • 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.

      • 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.

  • date (str, list[str], optional) – The portfolio date for which to retrieve data. The format is YYYY-MM-DD. For example, “2020-01-01”. If a date is provided, then the start_date and end_date parameters are ignored. Can also be a list of dates. The list can contain a maximum of 20 dates. An exception is thrown if start_date or end_date is provided along with date.

  • start_date (str, optional) – The start date for retrieving data. The format is YYYY-MM-DD. For example, “2020-01-01”. An exception is thrown if date is provided along with start_date.

  • end_date (str, optional) – The end date 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”. An exception is thrown if date is provided along with end_date.

  • data_points (Union, optional) –

    Defines the data points to fetch. If no data points are provided, a default list of data points with predefined aliases are returned, below are the list of default data points and associated aliases.

    • Data Point IDs (List[Dict], optional): A list of dictionaries, each defining a data point and its (optional) associated settings. If alias is provided in the datapoint setting, it will be used as the column name in the returned DataFrame. Otherwise, the data point ID will be used as the column name.

    • 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.

  • frequency (md.direct.data_type.Frequency, optional) –

    Frequency at which data point values are retrieved. The default is Frequency.monthly.

    • daily: Portfolio holdings data reported daily.

    • monthly: Portfolio holdings data reported on or close to the month-end calendar dates.

  • holdings_view (Union, optional) –

    Specifies the level of detail returned for portfolio holdings. This can be an integer or md.direct.data_type.HoldingsView. The default is HoldingsView.FULL.

    • Integer Value N: Returns only top N holdings for each portfolio.

    • FULL: Returns all available holdings for the portfolio on requested dates.

    • BEST_AVAILABLE: Returns the most complete holdings data available for each requested date.

  • suppression_client_id (str, optional) – If you have a privileged access to suppressed portfolios and would like to apply it, provide your Client ID.

  • enrichment_type (md.direct.data_type.EnrichmentType, optional) –

    Specifies the enrichment type of the data returned. The default is EnrichmentType.POINT_IN_TIME.

    • LATEST_AVAILABLE: Uses the most current data at feed generation time.

    • POINT_IN_TIME: Matches the data to each portfolio’s effective date.

    • LATEST_MONTH_END: Uses the latest available month-end data at request time.

  • 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.

  • preview (bool, optional) – Defaults to False. Setting to True allows access to data points outside of your current subscription, but limits the output to 25 rows.

Returns:

There are two return types:

DataFrame: A DataFrame object with holdings data. DataFrame columns include

  • masterPortfolioId

  • investmentId

  • portfolioCurrency

  • portfolioDate

  • holdingsView

  • holdingStorageId

  • secId

  • name

  • defaultHoldingTypeCode

  • weight

  • Other columns based on requested data points (column name will be the alias if provided, otherwise the data point ID)

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

Examples:

Retrieve the look-through holdings for a portfolio.

import morningstar_data as md

df = md.direct.get_lookthrough_holdings(investments=["FOUSA00KZH"], date="2020-12-31")
df
Output:

masterPortfolioId

investmentId

…

defaultHoldingTypeCode

weight

1356725

F00000WK3T

…

E

11.16649

1356725

F00000WK3T

…

E

10.49672

…