Guide
There are two ways to build a screener: by either asking the AI or building your own query. In this document, we will focus on building your queries for advanced use cases. While AI can help, it is not perfect, so it's always a good idea to review the query it generates.
Pre-defined Variables
We offer over 100 fundamental filters you can use. You can find detailed descriptions of these filters by visiting the appropriate page.
Basic Filtering
Example 1
Filter for companies with EBITDA greater than 5 million:
{
"fundamentals": {
"and": [
{"ebitda": {"gt": 5000000}}
]
},
"columns": ["ticker", "fiscalperiod", "date", "ebitda"]
}Example 2
Filter for companies with EBITDA greater than 5 million and a market cap between 1 and 5 billion:
{
"fundamentals": {
"and": [
{"ebitda": {"gt": 5000000}},
{"marketcap": {"between": [1000000000, 5000000000]}}
]
},
"columns": ["ticker", "fiscalperiod", "date", "ebitda"]
}Additional Columns
You can include additional columns in the output, such as price and volume data. However, only predefined and user-defined variables are permitted.
{
"fundamentals": {
"and": [
{"ebitda": {"gt": 5000000}},
{"marketcap": {"between": [1000000000, 5000000000]}}
]
},
"columns": ["ticker", "date", "open", "high", "low", "close", "volume"]
}Prevent browser hangs using "max_tickers"
Handling large data sets can potentially cause your browser to hang, so it's recommended to limit the number of tickers displayed in a single result.
{
"max_tickers": 100,
"fundamentals": {
"and": [
{"ebitda": {"gt": 5000000}},
{"marketcap": {"between": [1000000000, 5000000000]}}
]
},
"columns": ["ticker", "date", "open", "high", "low", "close", "volume"]
}Point-in-Time Screening
We have a historical dataset from January 1998 until today. You can do historical scans by using point_in_time parameter
{
"point_in_time": "2023-12-01",
"max_tickers": 100,
"fundamentals": {
"and": [
{"ebitda": {"gt": 5000000}},
{"marketcap": {"between": [1000000000, 5000000000]}}
]
},
"columns": ["ticker", "date", "open", "high", "low", "close", "volume"]
}Logical Operators
We support logical operators such as and and or.
Root "and" Operator
At least one and operator is required within the fundamentals or technicals filters. The first and is known as the root logical operator.
{
"fundamentals": {
"and": []
},
"daily": {
"and": []
}
}You cannot have two or more root logical operators:
{
"fundamentals": {
"and": [],
"and": []
},
"daily": {
"and": []
}
}Instead, you should use nesting:
{
"fundamentals": {
"and": [
{"or": [
{"ebitda": {"gt": 5}},
{"revenue": {"gt": 100}}
]}
]
},
"daily": {
"and": []
}
}There are no limits on how many nested logical operators you can use, but be aware that complex queries may slow down the screener.
Comparison Operators
We have used the gt (greater than) operator so far, but other comparison operators are supported:
eq: equal toneq: not equal togt: greater thangte: greater than or equal tolt: less thanlte: less than or equal tobetween: within a specified range
Example of eq Operator
eq OperatorEBITDA is equal to 5 million:
{
"fundamentals": {
"and": [
{"ebitda": {"eq": 5000000}}
]
}
}Example of neq Operator
neq OperatorEBITDA is not equal to 5 million:
{
"fundamentals": {
"and": [
{"ebitda": {"neq": 5000000}}
]
}
}Example of gt Operator
gt OperatorEBITDA is greater than 5 million:
{
"fundamentals": {
"and": [
{"ebitda": {"gt": 5000000}}
]
}
}Example of gte Operator
gte OperatorEBITDA is greater than or equal to 5 million:
{
"fundamentals": {
"and": [
{"ebitda": {"gte": 5000000}}
]
}
}Example of lt Operator
lt OperatorEBITDA is less than 5 million:
{
"fundamentals": {
"and": [
{"ebitda": {"lt": 5000000}}
]
}
}Example of lte Operator
lte OperatorEBITDA is less than or equal to 5 million:
{
"fundamentals": {
"and": [
{"ebitda": {"lte": 5000000}}
]
}
}Example of between Operator
between OperatorEBITDA is between 5 and 7 million:
{
"fundamentals": {
"and": [
{"ebitda": {"between": [5000000, 7000000]}}
]
}
}Defining Variables
You can assign a variable with a number, a mathematical expression, by aliasing a predefined variable or a combination of both. The variable name must always begin with a non-numeric character.
{
"variables": {
"fundamentals": {
"alias_for_ebitda": "ebitda",
"something_that_has_two": 2,
"sample_math": "2 * 10",
"math_with_predefined_var": "ebitda * 2"
},
"daily": {
"today_closed": "close"
}
}
}Variable names with number prefix is not allowed:
{
"variables": {
"fundamentals": {"2invalid_named_variable: "ebitda"}
},
}Defining a Mathematical Formula
The following basic mathematical operations are supported:
+ (Addition), - (Subtraction), * (Multiplication), / (Division), and parentheses () for grouping.
For example, if you want to create a custom filter for (ebitda + revenue) * 2, you would define a variable as follows:
{
"variables": {
"fundamentals": {"my_formula": "(ebitda + revenue) * 2"}
}
}You can then use the variable my_formula inside the fundamentals filter. Sorting is also supported:
{
"variables": {
"fundamentals": {"my_formula": "(ebitda + revenue) * 2"}
},
"fundamentals": {
"and": [
{"my_formula": {"gt": 5}}
],
"sort": {"my_formula": "desc"}
},
"columns": ["ticker", "fiscalperiod", "date", "my_formula"]
}Advanced Functions
Using the previous Function
previous FunctionThe previous function allows you to reference the value of a variable from previous rows. The syntax for the previous function is as follows:
{
"variables": {
"fundamentals": {
"name": {"function": "previous", "args": ["var", n]}
}
}
}var: This is the name of the variable (pre-defined or user-defined) whose previous value you want to retrieve.n: This is the number of periods you want to look back. For example,n=1would retrieve the value from the previous period.
Example 1: Getting Yesterday's Closing Price
In this example, we want to get the closing price from the previous day (yesterday's closing price), and then filter for cases where yesterday's closing price was greater than 500.
{
"variables": {
"daily": {
"previous_day_closed": {"function": "previous", "args": ["close", 1]}
}
},
"daily": {
"and": [
{"previous_day_closed": {"gt": 500}}
]
},
"columns": ["ticker", "fiscalperiod", "date", "previous_day_closed"]
}Example 2: Getting Last Year's Closing Price
In this example, we want to get the last year's closing price, and then filter for cases where price is greater than 500
{
"variables": {
"yearly": {
"previous_year_close": {"function": "previous", "args": ["close", 1]}
}
},
"yearly": {
"and": [
{"previous_year_close": {"gt": 500}}
]
},
"columns": ["ticker", "fiscalperiod", "date", "previous_day_closed"]
}Using the average Function
average FunctionThe average function calculates a simple moving average. Here’s how it is structured:
{
"variables": {
"fundamentals": {
"name": {"function": "average", "args": ["var", n]}
}
}
}var: Represents the name of the variable (either pre-defined or user-defined) that you want to calculate the average for.
n: Specifies the number of periods over which to calculate the average. For example,
n=5would compute a 5-day moving average for a stock.t (optional): Can define the time frame such as daily, weekly, monthly, or yearly.
Example 1: 200-day Moving Average of the Closing Price
In this case, the goal is to calculate the 200-day moving average of a stock's closing price.
{
"variables": {
"daily": {
"200_day_sma": {"function": "average", "args": ["close", 200, "day"]}
}
},
"daily": {
"and": [
{"200_day_sma": {"gt": "close"}}
]
},
"columns": ["ticker", "date", "close", "200_day_sma"]
}This example computes the 200-day simple moving average (SMA) of the closing price and then checks if the 200-day SMA is greater than the current closing price.
Getting Help with Queries from the AI Assistant
If you're having trouble correcting a query or are unsure of the filter name, you can always ask the AI assistant for help.
Last updated