---
title: "Filter Conditions"
description: "Learn how filter conditions work in the Equities Screener API: their structure, the three types, value formats and how to choose the right filter."
url: "https://developer-beta.morningstar.com/equities-screener-api/filter-conditions"
image: "https://developer-beta.morningstar.com/_og/d/c_Ocean.takumi,title_~RmlsdGVyIENvbmRpdGlvbnMgfCBFcXVpdGllcyBTY3JlZW5lciBBUEk,description_~TGVhcm4gaG93IGZpbHRlciBjb25kaXRpb25zIHdvcmsgaW4gdGhlIEVxdWl0aWVzIFNjcmVlbmVyIEFQSTogdGhlaXIgc3RydWN0dXJlLCB0aGUgdGhyZWUgdHlwZXMsIHZhbHVlIGZvcm1hdHMgYW5kIGhvdyB0byBjaG9vc2UgdGhlIHJpZ2h0IGZpbHRlci4,props_eyJ0aGVtZSI6eyJtb2RlIjoibGlnaHQiLCJjb2xvcnMiOnsicHJpbWFyeSI6IiMwMDAwMDAifX19,p_Ii9lcXVpdGllcy1zY3JlZW5lci1hcGkvZmlsdGVyLWNvbmRpdGlvbnMi,s_ssLAuyUrD0SvI-2E.png"
---

-   [APIs](https://developer-beta.morningstar.com/apis)
-   [API Catalog](https://developer-beta.morningstar.com/api-catalog)
-   [API Assistant MCP Server](https://developer-beta.morningstar.com/api-assistant-mcp)
-   [Guides](https://developer-beta.morningstar.com/api-guides)
-   [Trial Access](https://developer-beta.morningstar.com/trial-access)

# Equities Screener API

Powerful, criteria-based screening using flexible filtering logic.

# Filter Conditions

[View Markdown](https://developer-beta.morningstar.com/equities-screener-api/filter-conditions.md)[Download Markdown](https://developer-beta.morningstar.com/equities-screener-api/filter-conditions.md)

Filter conditions decide which investments a screen returns. They are the most important and most complex part of a request, so they have their own section. This page explains how filter conditions are built and how to choose between the types. The pages in this section cover each type in detail.

## [Anatomy of a Filter Condition](#anatomy-of-a-filter-condition)

A filter condition applies to one data point. It names the data point and gives a value, a list of values, or a comparison.

```json
{
  "<dataPoint>": "<value, list of values, or comparison>"
}
```

The following examples show the three forms.

```json
{ "shareClassInformation.symbol": "MSES" }
```

```json
{ "shareClassInformation.symbol": ["MSES", "CA40"] }
```

```json
{ "marketCapital.asOfDate": { "gt": "2020-01-01", "lt": "2024-01-01" } }
```

Filter conditions can be combined into larger conditions with `and`, `or` and `not`, and the combinations can be nested.

## [Where Filter Conditions Apply](#where-filter-conditions-apply)

Filter conditions are used in two parts of a request, and the syntax is the same in both.

| Property | Use                                                                              |
| :------- | :------------------------------------------------------------------------------- |
| scope    | Sets the starting universe. For equities, it is defined with the exchange code data point. See Screen Equities. |
| query    | Narrows the scoped universe. If you omit it, the screen returns everything in the scope. |

## [Types of Filter Conditions](#types-of-filter-conditions)

| Type       | What It Does                                         | Page                      |
| :--------- | :--------------------------------------------------- | :------------------------ |
| Equality   | Matches an exact value, or any value in a list.      | Equality and Text Filters |
| Text       | Searches text by substring or by approximate match.  | Equality and Text Filters |
| Comparison | Compares numbers and dates with gt, gte, lt and lte. | Comparison Filters        |
| Compound   | Combines conditions with and, or and not.            | Compound Filters          |

## [Choose the Right Filter](#choose-the-right-filter)

The data type of a data point determines which filters you can use. Check the metadata for the data point, as described in [Explore Data Points](https://developer-beta.morningstar.com/equities-screener-api/explore-data-points).

| Data Type | Filters You Can Use                                        |
| :-------- | :--------------------------------------------------------- |
| boolean   | Equals.                                                    |
| date      | Equals, in, and range comparisons.                         |
| number    | Equals, in, and range comparisons.                         |
| string    | Equals and in. Some data points also support fuzzy search. |

The `operators` property of each data point lists the operators it supports. Use only those operators on that data point.

## [Value Formats](#value-formats)

| Value   | Format                                   | Example          |
| :------ | :--------------------------------------- | :--------------- |
| Text    | A JSON string.                           | "MSES"           |
| Number  | A JSON number, with no quotation marks.  | 4, 0.453506      |
| Boolean | true or false, with no quotation marks.  | true             |
| Date    | A string in yyyy-MM-dd format.           | "2024-03-31"     |
| List    | A JSON array of values of the same type. | ["MSES", "CA40"] |

## [Combine Filters](#combine-filters)

Use a compound filter whenever a query needs more than one condition. It makes the logic explicit, so that the query means the same thing to everyone who reads it.

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

## [Quick Reference](#quick-reference)

| To Do This                     | Use This Syntax                                         |
| :----------------------------- | :------------------------------------------------------ |
| Match one value                | { "<dataPoint>": "<value>" }                            |
| Match any value in a list      | { "<dataPoint>": ["<value1>", "<value2>"] }             |
| Search text for a substring    | { "<dataPoint>": { "contains": "<text>" } }             |
| Search text approximately      | { "<dataPoint>": { "value": "<text>", "fuzzy": true } } |
| Compare numbers or dates       | { "<dataPoint>": { "gt": <value>, "lt": <value> } }     |
| Require all conditions         | { "and": [ <condition>, <condition> ] }                 |
| Require at least one condition | { "or": [ <condition>, <condition> ] }                  |
| Exclude conditions             | { "not": [ <condition>, <condition> ] }                 |