InvestmentIdentifier#

class morningstar_data.direct.InvestmentIdentifier(
sec_id: 'Optional[str]' = None,
ticker: 'Optional[str]' = None,
cusip: 'Optional[str]' = None,
isin: 'Optional[str]' = None,
base_currency: 'Optional[str]' = None,
exchange: 'Optional[str]' = None,
)#

New in version 1.11.0.

The InvestmentIdentifier class resides in the morningstar_data.direct module, serving as the standardized input mechanism for security resolution across the get_investment_data() and lookup.investments() functions. Importation follows standard Python patterns:

from morningstar_data.direct import InvestmentIdentifier

This class allows users to specify investments using identifiers beyond the Morningstar Security ID (sec_id). You can specify investments using a combination of:

  • sec_id

  • isin

  • cusip

  • ticker

  • base_currency

  • exchange

The function attempts to find the best match based on a ranking methodology.

Properties:

  • sec_id (str, optional): Morningstar’s primary internal identifier that maps to a single security. Example: “0P0000EEPX” for Apple Inc’s Wiener Boerse AG listing.

  • isin (str, optional): International Securities Identification Number (12-character alphanumeric, ISO 6166 standard). Example:”US0378331005”for Apple Inc’s NASDAQ listing.

  • cusip (str, optional): Committee on Uniform Securities Identification Procedures number (9-character, ANSI X9.6-2016 standard). Example:”037833100”for Apple’s US common stock.

  • ticker (str, optional): Exchange-issued symbol (1-10 character length, case-insensitive). Example:”AAPL”for Apple’s primary ticker.

  • base_currency (str, optional): 3-letter ISO 4217 currency code or an abbreviated currency code. Example:”CAD” or “Canadian Dollar”for CAD-denominated listings.

  • exchange (str, optional): Official exchange name or abbreviation (MIC database, ISO 10383). Example: “Nasdaq” for NASDAQ’s market identifier code.

Important Considerations#

  • ISIN, CUSIP, and Ticker: When using these identifiers, the function attempts to find the best match based on the security matching logic.

  • Base Currency and Exchange: These parameters refine search results for best match searches. It is highly recommended to use these in combination with ISIN, CUSIP, or ticker whenever possible to narrow down the results and specify the exact listing you are looking for. Both of these fields will match fuzzily, for example “Toronto Exchange” would match “Toronto Stock Exchange”.

  • Prioritization: When multiple properties are specified in a single InvestmentIdentifier object, the function prioritizes investments that match all specified criteria. However, if a sec_id is provided in an InvestmentIdentifier object, it takes absolute precedence. The function will return the investment matching this sec_id, disregarding all other identifiers.

Usage Examples#

These examples demonstrate how to create InvestmentIdentifier objects with different combinations of properties.

  1. Only ISIN

from morningstar_data.direct import InvestmentIdentifier

data_point_ids = [
    {"datapointId": "LS05M"}, # Base Currency
    {"datapointId": "LS01Z"}, # Exchange by Name
]
investments = [InvestmentIdentifier(isin="US0378331005")] # Apple Inc. (best match)

df = md.direct.get_investment_data(investments, data_point_ids)
df

Id

Name

Base Currency

Exchange

0P000000GY

Apple Inc

US Dollar

Nasdaq - All Markets

  1. Only CUSIP

from morningstar_data.direct import InvestmentIdentifier

data_point_ids = [
    {"datapointId": "LS05M"}, # Base Currency
    {"datapointId": "LS01Z"}, # Exchange by Name
]
investments = [InvestmentIdentifier(cusip="037833100")] # Apple Inc. (best match)

df = md.direct.get_investment_data(investments, data_point_ids)
df

Id

Name

Base Currency

Exchange

0P000000GY

Apple Inc

US Dollar

Nasdaq - All Markets

  1. Only Ticker

from morningstar_data.direct import InvestmentIdentifier

data_point_ids = [
    {"datapointId": "LS05M"}, # Base Currency
    {"datapointId": "LS01Z"}, # Exchange by Name
]
investments = [InvestmentIdentifier(ticker="AAPL")]  # Apple Inc. (best match)

df = md.direct.get_investment_data(investments, data_point_ids)
df

Id

Name

Base Currency

Exchange

0P000000GY

Apple Inc

US Dollar

Nasdaq - All Markets

  1. Ticker with Base Currency

from morningstar_data.direct import InvestmentIdentifier

data_point_ids = [
    {"datapointId": "LS05M"}, # Base Currency
    {"datapointId": "LS01Z"}, # Exchange by Name
]
investments = [InvestmentIdentifier(ticker="AAPL", base_currency="EUR")]  # Apple Inc. listed in EUR

df = md.direct.get_investment_data(investments, data_point_ids)
df

Id

Name

Base Currency

Exchange

0P0000EEPX

Apple Inc

Euro

Wiener Boerse AG

  1. Ticker with Exchange

from morningstar_data.direct import InvestmentIdentifier

data_point_ids = [
    {"datapointId": "LS05M"}, # Base Currency
    {"datapointId": "LS01Z"}, # Exchange by Name
]
investments = [InvestmentIdentifier(ticker="MSFT", exchange="Toronto Stock Exchange")]  # Microsoft Corp. on the TSX

df = md.direct.get_investment_data(investments, data_point_ids)
df

Id

Name

Base Currency

Exchange

0P0001NHUC

Microsoft Corp Canadian Depository Receipt

Canadian Dollar

Toronto Stock Exchange

  1. Ticker with Base Currency and Exchange (most specific)

from morningstar_data.direct import InvestmentIdentifier

data_point_ids = [
    {"datapointId": "LS05M"}, # Base Currency
    {"datapointId": "LS01Z"}, # Exchange by Name
]
investments = [InvestmentIdentifier(ticker="AAPL", base_currency="EUR", exchange="Wiener Boerse AG")]  # Apple Inc. listed in EUR on the Vienna Stock Exchange

df = md.direct.get_investment_data(investments, data_point_ids)
df

Id

Name

Base Currency

Exchange

0P0000EEPX

Apple Inc

Euro

Wiener Boerse AG

Security Matching Logic#

The system prioritizes results using a model designed to surface the most significant listings.

Key Influencing Factors#

The algorithm incorporates:

  • Parameters passed to InvestmentIdentifier (e.g. Ticker, ISIN, Exchange)

  • Fund Size / Market Capitalization

  • Trading Volume

Composite Match Quality:

# Superior to standalone ticker
InvestmentIdentifier(ticker="MSFT", exchange="XNAS", base_currency="USD")
For best results:

  1. Be as specific as possible when specifying an InvestmentIdentifier. For example, multiple securities may match a given ISIN (e.g., “12345”). Including additional criteria—such as the currency (e.g., “USD”)—can help narrow down the results to a single match.

  2. It is recommended to validate potential matches using lookup.investments() before retrieving data. This function returns all possible matches for the provided InvestmentIdentifier and can assist in identifying the necessary criteria to accurately target the desired security.