---
title: "Comparison Filters"
description: "Filter numbers and dates in the Equities Screener API using greater than, less than and range comparisons."
url: "https://developer-beta.morningstar.com/equities-screener-api/comparison-filters"
image: "https://developer-beta.morningstar.com/_og/d/c_Ocean.takumi,title_~Q29tcGFyaXNvbiBGaWx0ZXJzIHwgRXF1aXRpZXMgU2NyZWVuZXIgQVBJ,description_~RmlsdGVyIG51bWJlcnMgYW5kIGRhdGVzIGluIHRoZSBFcXVpdGllcyBTY3JlZW5lciBBUEkgdXNpbmcgZ3JlYXRlciB0aGFuLCBsZXNzIHRoYW4gYW5kIHJhbmdlIGNvbXBhcmlzb25zLg,props_eyJ0aGVtZSI6eyJtb2RlIjoibGlnaHQiLCJjb2xvcnMiOnsicHJpbWFyeSI6IiMwMDAwMDAifX19,p_Ii9lcXVpdGllcy1zY3JlZW5lci1hcGkvY29tcGFyaXNvbi1maWx0ZXJzIg,s_Rb8XK1F514c8Rekn.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.

# Comparison Filters

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

Comparison filters select investments whose data point is above, below or between values. Use them with numbers and dates.

## [Comparison Operators](#comparison-operators)

| Operator | Meaning                   |
| :------- | :------------------------ |
| gt       | Greater than.             |
| gte      | Greater than or equal to. |
| lt       | Less than.                |
| lte      | Less than or equal to.    |

Write the operators inside an object, as the value of the data point.

```json
{
  "<dataPoint>": {
    "gt": "<value>",
    "lt": "<value>"
  }
}
```

`gt` and `lt` are exclusive, so a value equal to the limit isn't matched. `gte` and `lte` are inclusive, so a value equal to the limit is matched.

The comparison object must contain at least one operator, and can't contain anything else.

## [Compare Numbers](#compare-numbers)

The following query returns investments whose 24-month beta is greater than 4 and less than 10.

```json
"query": {
  "dividendResidualRiskAndReturnSensitivity.beta24Month": {
    "gt": 4,
    "lt": 10
  }
}
```

Write numbers without quotation marks.

## [Compare Dates](#compare-dates)

Write dates as strings in `yyyy-MM-dd` format. The following query returns investments whose market capital date is between 1 January 2020 and 31 March 2024, exclusive.

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

## [Set One Limit or Both](#set-one-limit-or-both)

You can set a limit on one side only, or on both sides to create a range.

| To Return             | Use                                                     |
| :-------------------- | :------------------------------------------------------ |
| Values above a limit  | { "gt": <value> } or { "gte": <value> }                 |
| Values below a limit  | { "lt": <value> } or { "lte": <value> }                 |
| Values within a range | One lower limit and one upper limit in the same object. |

To include the limits in a range, use `gte` and `lte`.

```json
"query": {
  "marketCapital.asOfDate": {
    "gte": "2024-01-01",
    "lte": "2024-12-31"
  }
}
```

## [Check That the Data Point Supports the Operator](#check-that-the-data-point-supports-the-operator)

Only data points whose metadata lists the operator support it. In particular, a string data point usually supports only equality filters. Some values that represent dates are stored as strings, and the metadata for those data points can list the comparison operators, so use the `operators` property rather than the data type to decide. See [Explore Data Points](https://developer-beta.morningstar.com/equities-screener-api/explore-data-points).

## [Combine Comparisons with Other Filters](#combine-comparisons-with-other-filters)

To apply a comparison together with other conditions, put them in an `and` or `or` filter.

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

See [Compound Filters](https://developer-beta.morningstar.com/equities-screener-api/compound-filters).