Equities Screener API

Powerful, criteria-based screening using flexible filtering logic.

Filter Conditions

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

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

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

The following examples show the three forms.

{ "shareClassInformation.symbol": "MSES" }

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

{ "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

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

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

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.

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	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

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.

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

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> ] }`