On this page, we will collect the changes in our API that are necessary to adapt to Morningstar’s rework. Depending on how your systems are designed, they might require adjustments on your side.
subtype. (Update: This change was removed from the scope of the upgrade. Therefore, nothing changes for you) We’ll start populating the field subType with the value SP when type=SPINOFF. Currently, it’s empty. This will ensure consistency and allow clients to determine the type of a corporate action using only one field – subtype or type – instead of needing to use both.
Rights Issues and Capital Repayment. Two new types of corporate actions are being added: Rights Issues and Capital Repayment.
- A capital repayment is a return of capital similar to a special dividend but it has different tax treatment. It is being collected for all companies globally, but it is typically only used by companies in the United Kingdom. There would not be any adjustment made to historical price data and per share data, however, these would be considered while calculating Total Return, similar to a Special Cash Dividend event.
- A right issue opt by a company is intended to raise new capital by new shares issued/offered to existing shareholders in proportion to their current shareholding, for a specified period and at a specified (usually discounted) price. For example, in a two-for-five rights issue, stockholders are offered two shares for every five they already hold at a discounted price.
- From the technical point of view, 2 new values arise for the type field (“RIGHTS_ISSUES” for Rights Issues and “CAPITAL_REPAYMENT” for Capital Repayment) and for the subtype field (“RI” for Rights Issues and “CR” for Capital Repayment).
taxRate. We are adding a new extension field: taxRate. It contains the withholding tax rate: the tax rate applicable to the gross dividend amount (stored in adjustmentValue) to derive the net amount for cash dividends to derive the Cash Dividend Net Amount. The Cash Dividend Net Amount is displayed in the adjustmentValue field for cash dividends.
fiscalYearEndMonth. (Update: This field will continue to be populated as we found the way to populate it on our side. Therefore, nothing changes for you). The extension field fiscalYearEndMonth is retired and will be empty from now on. It will, however, persist in the Earning Report controller.
normalizedBasicEPS. This field is retired and will be populated with NaN value from now on. Please use reportedNormalizedBasicEPS instead.
normalizedDilutedEPS. This field is retired and will be populated with NaN value from now on. Please use reportedNormalizedDilutedEPS instead.
srcExchange. Due to the transition from legacy localized datasets to a global schema, the field srcExchange in the Instrument Reference controller will be updated to ensure consistency across regions and products. Currently, it contains values such as (PINX, NYS, ASE, etc.). After the update, its values will be (OTCPK, NYSE, AMEX, etc.). It will not affect the exchange code encoded in dxSymbol.
industryTemplateCode. Possible values for the field industryTemplateCode will change, reflecting the change in methodology:
- Current possible values: N (Manufacturing), B (Bank), I (Insurance), M (Mining), U (Utility), T (Transportation).
- New possible values: N (Normal), B (Bank), I (Insurance), V (Investment).
tradingStatus. The extension field tradingStatus may now be absent in the API responses when no status is available.
isDirectInvest. The extension field isDirectInvest is retired and will not be returned via API for all new records. It will, however, continue being returned for historical records.
advisorType. We are adding a new advisorType field. It provides more transparency on the role of advisor. Examples are:
- Solicitor
- Financial Adviser
- Remuneration Consultant
- Bank
- Stockbroker
Also, previously, when there was no information about a company’s advisor, auditor name was copied into the field “advisor”. Now we don’t do that and leave the field “advisor” empty or populate it with actual advisor wherever we have information.
isDividendReinvest. The extension field isDividendReinvest is retired and will not be returned via API for all new records. It will, however, continue being returned for historical records.
shareClassDescription. (Update: Morningstar reverted this change. Therefore, nothing changes for you.) Previously, this field was populated only when it was necessary to indicate the share class, such as “Class A” or “Class B”. Now, it will contain both the share class and the share name, for example: “Berkshire Hathaway Inc. B” instead of just “Class B”. It means that clients no longer need to concatenate shareClassDescription with standardName or legalName to form a full name; instead, you can just use shareClassDescription. Also, this field will now always be populated, at least with the share name, for example: “Maruwa Co., Ltd”.
reportStyle. The extension field reportStyle is retired and will not be returned via API for all new records. It will, however, continue being returned for historical records.
depositaryReceiptRatio. Currently, this field is populated with a NaN (Not-a-Number) value for regular stocks (that are not depositary receipts). In the new format, Morningstar populates this field with a 1.0 value in such cases. You can use the isDepositaryReceipt field to distinguish between depositary receipts and regular stocks.
delistingReason. (Update: Morningstar returned this field instead of retiring it. Therefore, nothing changes for you.) The extension field delistingReason is retired and will be empty from now on.
notes. The extension field notes is retired and will be empty from now on.
fiscalYearEndMonth. (Update: This field will continue to be populated as we have found a way to populate it on our side. Therefore, nothing changes for you) The extension field fiscalYearEndMonth is retired and will be empty from now on. It will, however, persist in the Earning Report controller.
Morningstar no longer converts 4 fields (salesPerShare, bookValuePerShare, operationsCashFlowPerShare, cashFlowFreePerShare) to the trading currency; from now on, they will be expressed in the reporting currency. Trading currency is the currency in which this instrument is being traded on an exchange. You can find this currency in the currencyCode field in the Instrument Reference. Reporting currency is the currency in which this company files its financial reports. You can find this currency in the currencyCode field in the Balance Statement, Cash Flow Statement, Income Statement, Earning, or Earning Report. Other fields remain as they were in the old format: forwardPERatio, forwardDividendYield, peRatio, psRatio, pbvRatio, pcfRatio, pfcfRatio, and trailingDividendYield are in the trading currency; payoutRatio is in the reporting currency.