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:

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

Return type:

DataFrame

  • secId

  • masterPortfolioId

  • date

  • suppression

  • suppressionHoldingNumber

Examples

Retrieve portfolio dates for investment “FOUSA00KZH”.

import morningstar_data as md

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

secId

masterPortfolioId

date

suppression

suppressionHoldingNumber

FOUSA06JNH

210311

2021-08-31

False

None

FOUSA06JNH

210311

2021-07-31

False

None

…
morningstar_data.direct.get_holdings(
investments: List[str] | str | Dict[str, Any] | None = None,
date: str | None = None,
start_date: str | None = None,
end_date: str | None = None,
investment_ids: List[str] | None = None,
dry_run: bool | None = False,
) → DataFrame | DryRunResults#

Returns holdings for the specified investments and date or date range. If the date is not specified, 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.

  • date (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. 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”].

  • 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. Note: A few cells from your daily quota will be consumed in order to get the most recent number of holdings for each portfolio.

Returns:

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

  • investmentId

  • masterPortfolioId

  • portfolioDate

  • holdingId

  • bondId

  • name

  • secId

  • isin

  • cusip

  • weight

  • shares

  • marketValue

  • sharesChanged

  • currency

  • ticker

  • detailHoldingType

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

Return type:

There are two return types

Raises:

ValueErrorException – Raised when the investments parameter is 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:

investmentId

masterPortfolioId

…

ticker

detailHoldingType

FOUSA00KZH

6079

…

CBRE

EQUITY

FOUSA00KZH

6079

…

GOOGL

EQUITY

…