Universe API

1.0OAS 3.1

The Universe API is a utility to retrieve reference information for the investments in your entitled universe.

Overview

Use the Universe API to:

  • Get a custom universe.
  • Get universe entitlements.
  • Filter entitled universe and retrieve paginated results.

Core Concepts

Custom Universe

  • A named subset of an account’s full entitled universe.
  • A custom universe can be retrieved in full or narrowed further by applying filters.

Primary Filter

  • The primary filter is a required prerequisite filter that determines the top-level scope of the results.
  • A primary filter must be present before any secondary filter can be applied.
  • Only one primary filter can be used per request.
  • For equities, the primary filter is exchangeCode.
  • For managed investments, use either countryAvailableForSaleCode and domicileCode as the primary filter.

Secondary Filter

  • An optional filter that further narrows results within the scope set by the primary filter.
  • Secondary filters cannot be used without a primary filter, but multiple secondary filters can be combined in the same request.
  • Currently, secondary filters are supported for equities only.
  • For equities, the supported secondary filters are securityType, shareClassInformationInvestmentType.

Authentication API

  • Retrieve tokens required to authorize calls to the API.
  • See documentation.
API Base URL
  • Server 1:https://www.us-api.morningstar.com

    Americas Production

  • Server 2:https://www.apac-api.morningstar.com

    APAC Production

  • Server 3:https://www.eu-api.morningstar.com

    EMEA Production

Security
Bearer (http)

Obtain a token via the Authentication API’s POST /token/oauth endpoint. Tokens are valid for 60 minutes and reusable across requests.

Investments Universe

Query entitled universe to retrieve investment metadata

Get Universe Entitlements

Retrieve the primary filters your account is entitled for.

Scenario Request Inputs
Get equities entitlements. GET /investments
Get managed investments entitlements. GET /investments?source=managedInvestments

Get Custom Universe

Retrieve a custom universe in full.

Scenario Request Inputs
Get equities custom universe. GET /investments?universe=MY_EQUITIES_ABC
Get managed investments custom universe. GET /investments?source=managedInvestments&universe=MY_MANAGED_INVESTMENTS_XYZ

Filter Equities

Further narrow a custom universe or filter full universe.

Scenario Request Inputs
Filter custom universe by primary filter. GET /investments?exchangeCode=XPAR&universe=MY_EQUITIES_ABC
Filter custom universe by primary and secondary filter. GET /investments?exchangeCode=XPAR&securityType=ST00000001&universe=MY_EQUITIES_ABC
Filter full universe by primary filter only. GET /investments?exchangeCode=XPAR
Filter full universe by primary and 1 secondary filter. GET /investments?exchangeCode=XPAR&securityType=ST00000001
Filter full universe by primary and 2 secondary filters. GET /investments?exchangeCode=XPAR&shareClassInformationInvestmentType=ST00000001&securityType=ST00000001

Filter Managed Investments

Further narrow a custom universe or filter full universe.

Scenario Request Inputs
Filter custom universe by a primary filter. GET /investments?source=managedInvestments&domicileCode=USA&universe=MY_MANAGED_INVESTMENTS_XYZ
Filter managed investments by a primary filter (countryAvailableForSaleCode) GET /investments?source=managedInvestments&countryAvailableForSaleCode=USA
Filter managed investments by a primary filter (domicileCode) GET /investments?source=managedInvestments&domicileCode=USA

Retrieve Results Using Pagination Tokens

Set pagination preferences in inital request and retrieve paginated results using tokens.

Scenario Request Inputs
Pagination settings initial request (default pageSize). GET /investments?exchangeCode=XPAR
Pagination settings subsequent requests (default pageSize). GET /investments?exchangeCode=XPAR&paginationTokenNext=CJjVEBoTOhE
Pagination settings initial request (explicit pageSize). GET /investments?exchangeCode=XPAR&pageSize=25
Pagination settings subsequent requests (explicit pageSize). GET /investments?exchangeCode=XPAR&pageSize=25&paginationTokenNext=CJjVEBoTOhE
get

Query Parameters

universestring

Filters results to a custom universe defined during implementation for the account.

Example:MY_UNIVERSE_321

sourcestring

Specifies the investment data type to query.

Allowed values:equitiesmanagedInvestments

Default:equities

exchangeCodestring

Primary filter for equities. Filters results by exchange code.

Example:XPAR

securityTypestring

Secondary filter for equities. Accepts:

  • ST00000001 - Common Stock
  • ST00000002 - Preferred Stock
  • ST00000003 - Industry
  • ST00000004 - Index
  • ST00000005 - ETF
  • ST00000006 - Closed-end Fund
  • ST00000007 - Investment Trusts
  • ST00000008 - Warrant
  • ST00000009 - Note
  • ST000000A1 - Units
  • ST000000B1 - Rights
  • ST000000C1 - Unlisted Common
  • ST000000C2 - Unlisted Preferred

Allowed values:ST00000001ST00000002ST00000003ST00000004ST00000005ST00000006ST00000007ST00000009ST00000008ST000000A1ST000000B1ST000000C1ST000000C2

Example:ST00000001

countryAvailableForSaleCodestring

Primary filter for managed investments. Accepts 3-character ISO 3166-1 country codes.

Example:AUS

domicileCodestring

Primary filter for managed investments. Accepts 3-character ISO 3166-1 country codes.

Example:AUS

shareClassInformationInvestmentTypestring

Secondary filter for equities.

Accepts:

  • EQ - Equity
  • DR - Depository Receipt
  • PE - Preferred Equity
  • UE - Unlisted Equity

Allowed values:EQDRPEUE

Example:EQ

paginationTokenNextstring

Specifies the token to fetch the next page of results.

Example:CJ2aBBoROg81YmFuYyBzcGxpdCBpbmMaDDoKMHAwMDAwbTJkaiIMOgowUDAwMDBNMkRK

paginationTokenPreviousstring

Specifies the token to fetch the previous page of results.

Example:CJ2aBBoROg81YmFuYyBzcGxpdCBpbmMaDDoKMHAwMDAwbTJkaiIMOgowUDAwMDBNMkRK

pageSizeinteger(int32)

Specifies the number of records per page.

Default:50

>= 1<= 50

Example:25

Response

application/json

200: OK

ResponseInvestments

Response containing investment results and metadata.

investmentsarray[object]required

Investment entry returned as part of the universe lookup.

* Additional properties are allowed.
Show Child Parameters
metadataobjectrequired
Show Child Parameters
get/direct-web-services/v1/investments
 
application/json