Screen Equities

A screen is one request that says where to look, what to look for and what to return. This page walks through building a complete request, one part at a time. For the ideas behind each part, see Core Concepts.

Request Overview

To run a screen, send a POST request to the screener endpoint.

POST /direct-web-services/v1/screeners/equities

Use the base URL for your region, as described in Getting Started. The request must include the following headers.

The body is a JSON object. Build it in the following steps.

Step 1: Define the Scope

The scope sets the starting universe of investments, limited to your entitled universe. A request must include a scope. For equities, the scope is defined with the exchange code data point.

"scope": {
  "shareClassInformation.exchangeCode": "XPAR"
}

The scope is written in the same way as a query. You can pass a list of values to include several exchanges, or use a compound filter. If you use a compound filter, each branch must contain the exchange code data point. See Compound Filters.

Step 2: Build Filter Conditions

The query narrows the scoped universe with filter conditions. If you omit it, the screen returns everything in the scope.

A single condition names a data point and a value.

"query": {
  "shareClassInformation.securityType": ["ST00000001", "ST00000002"]
}

To combine conditions, use and, or and not. The following query returns securities of the given types with a market capital date after 1 January 2024.

"query": {
  "and": [
    { "shareClassInformation.securityType": ["ST00000001", "ST00000002"] },
    { "marketCapital.asOfDate": { "gt": "2024-01-01" } }
  ]
}

Before you use a data point in a filter, check its metadata to confirm that it supports the operator you want. See Explore Data Points.

Filter conditions are the most important and most complex part of a request. For all the filter types, syntax and rules, see Filter Conditions.

Step 3: Select Data Points

The dataPoints array lists the data points to return for each match. This keeps responses small, because you only receive what you ask for.

• Each entry must be a valid data point name. See Explore Data Points.
• A request can include up to 100 data points.
• The performance ID is always returned. If you omit dataPoints, the performance ID is the only data point returned.

"dataPoints": [
  "shareClassInformation.symbol",
  "shareClassInformation.investmentName",
  "shareClassInformation.securityType",
  "marketCapital.asOfDate",
  "trailingReturn.trailing10YearReturn"
]

If a data point name isn't valid, the request fails with an error that lists the invalid names. See Errors.

Set the Language and Currency

Some data points depend on a language or a currency. The metadata for each data point shows which ones do.

For the full list of language codes, see API Inputs.

In the example above, trailingReturn.trailing10YearReturn is currency-dependent, so the request should include a currencyId.

"currencyId": "EUR"

Step 4: Set Sort Preferences

The sort array sets the order of the results. Each entry names a data point and a direction, asc or desc.

• Entries are applied in order.
• The data point must be sortable, and must also be in the dataPoints array.
• If you don't set a sort order, results are in ascending performance ID order.

"sort": [
  { "dataPoint": "marketCapital.asOfDate", "orderBy": "desc" }
]

Step 5: Paginate Results

Results are returned in pages. The pagination object sets the page size and moves you between pages.

To page through the results:

1. Send the first request without a token. Set pageSize if you want fewer than 50 results per page.
2. Read metadata.totalCount for the total number of matches, and metadata.paginationTokenNext for the next page token.
3. Send the same request again with the token in pagination.paginationTokenNext.
4. Repeat until you have all the results.

"pagination": {
  "pageSize": 25,
  "paginationTokenNext": "{token from the previous response}"
}

Use either the next token or the previous token in a request, not both. For how to read the tokens in the response, see Work with Results.

Send the Request

The following request combines all five steps.

curl --request POST \
  --url "https://www.us-api.morningstar.com/direct-web-services/v1/screeners/equities" \
  --header "Authorization: Bearer {token}" \
  --header "Content-Type: application/json" \
  --data '{
    "scope": {
      "shareClassInformation.exchangeCode": "XPAR"
    },
    "query": {
      "and": [
        { "shareClassInformation.securityType": ["ST00000001", "ST00000002"] },
        { "marketCapital.asOfDate": { "gt": "2024-01-01" } }
      ]
    },
    "dataPoints": [
      "shareClassInformation.symbol",
      "shareClassInformation.investmentName",
      "shareClassInformation.securityType",
      "marketCapital.asOfDate",
      "trailingReturn.trailing10YearReturn"
    ],
    "sort": [
      { "dataPoint": "marketCapital.asOfDate", "orderBy": "desc" }
    ],
    "pagination": {
      "pageSize": 25
    },
    "currencyId": "EUR"
  }'

The response contains the matching investments and metadata, including any warnings. See Work with Results.

For more complete requests, see Example Screens.

Request Limits

• A request can include a maximum of 100 data points.
• A page contains a maximum of 50 results. Use pagination to retrieve more.

Next Steps

• Filter Conditions covers every filter type in detail.
• Work with Results explains how to read the response and handle warnings.
• Example Screens has complete requests you can adapt.