API
ESC to close

Stock Screener

Screen and filter the entire market based on dynamic financial metrics, ratios, and conditions. Fetch exactly the columns and data points you need for your analysis.

POST https://data.businessquant.com/screener?page={page}&limit={limit}&api_key={api_key}

Parameters & Payload

The Screener endpoint requires authentication and pagination parameters passed in the URL (Query), alongside a JSON body payload defining your exact SQL-like filtering conditions and requested output columns.

Query Parameters

Parameter Description
api_key
Required
Your unique API key for authentication.
page
Optional
The page number for pagination. Default is 1.
Format: page=1
limit
Optional
The maximum number of records to return per page. Default is 10000.
Format: limit=500

JSON Body (Payload)

Key Description
conditions
Required String
A SQL-like syntax string to filter the market. Supports standard logical operators like AND, OR, and parentheses () for complex grouping. Wrap all metric names in double quotes " ".
Format: "conditions": "\"P/E Ratio\" < 15 AND (\"sector\" = 'Technology' OR \"sector\" = 'Healthcare')"
preferred_columns
Optional Array
An array of specific metric column names you want returned in the response alongside the base identification columns.
Format: "preferred_columns": ["Revenue (Yr)", "Net Income (Yr)"]
Example cURL Request 
curl -X POST "https://data.businessquant.com/screener?page=1&limit=50&api_key=YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "conditions": "\"Market Capitalization\" > 5000000000 AND \"P/E Ratio\" < 15 AND (\"sector\" = '\'Technology\'' OR \"sector\" = '\'Healthcare\'')",
  "preferred_columns": [
    "Revenue (Yr)", 
    "Net Income (Yr)", 
    "Dividend Yield"
  ]
}'
Sample Response 
{
    "metadata": {
        "total_records": 438,
        "total_pages": 9,
        "page": 1,
        "limit": 50
    },
    "data": [
        {
            "ticker": "AAPL",
            "cik": 320193,
            "name": "Apple Inc.",
            "name_short": "Apple",
            "sector": "Technology",
            "industry": "Consumer Electronics",
            "Market Capitalization": 2850000000000.0,
            "P/E Ratio": 18.52,
            "Revenue (Yr)": 383285000000.0,
            "Net Income (Yr)": 96995000000.0,
            "Dividend Yield": "0.53%"
        },
        {
            "ticker": "JNJ",
            "cik": 200406,
            "name": "Johnson & Johnson",
            "name_short": "J&J",
            "sector": "Healthcare",
            "industry": "Drug Manufacturers",
            "Market Capitalization": 375000000000.0,
            "P/E Ratio": 10.85,
            "Revenue (Yr)": 85159000000.0,
            "Net Income (Yr)": 35000000000.0,
            "Dividend Yield": "3.05%"
        }
    ]
}

Understanding the Syntax (Operators & Escaping Quotes)

Because the conditions parameter is passed as a single string within a JSON payload, any internal double quotes used to identify metric names must be escaped using a backslash (\"). Standard text values (like sector names) should use single quotes. You can build highly complex logical structures using AND, OR, and parentheses.

1. Standard SQL Logic:

"Market Capitalization" > 5000000000
AND "P/E Ratio" < 15
AND ("sector" = 'Technology' OR "sector" = 'Healthcare')

2. Final Escaped JSON (Paste directly into Postman Body):

Raw JSON 
{
  "page": 1,
  "limit": 50,
  "conditions": "\"Market Capitalization\" > 5000000000 AND \"P/E Ratio\" < 15 AND (\"sector\" = 'Technology' OR \"sector\" = 'Healthcare')",
  "preferred_columns": [
    "Revenue (Yr)", 
    "Net Income (Yr)", 
    "Dividend Yield"
  ]
}

Fetch Screener Metadata (Schema)

Before querying the screener, you can dynamically fetch the master list of all valid metric strings and datatypes available in our database using the /metadata endpoint.

GET https://data.businessquant.com/metadata?table=screener&api_key={api_key}
Example cURL Request 
curl -X GET "https://data.businessquant.com/metadata?table=screener&api_key=YOUR_API_KEY"

Understanding the Schema Response

The metadata endpoint acts as a programmatic dictionary for the screener. Use it to populate your UI filters or validate user inputs before sending a POST request.

  • metric_full: The exact string required for your conditions and preferred_columns payload parameters.
  • metric_short: A condensed, UI-friendly display name.
  • datatype: Tells your application how to format the result (e.g., as a number, or as a %).
  • statement: The financial category where this metric originates (e.g., Overview, Valuation Ratios).
Sample Schema Response 
[
    {
        "metric_full": "Market Capitalization",
        "metric_short": "Market Cap",
        "datatype": "number",
        "statement": "Overview"
    },
    {
        "metric_full": "P/E Ratio",
        "metric_short": "P/E Ratio",
        "datatype": "number",
        "statement": "Valuation Ratios"
    },
    {
        "metric_full": "Gross Profit Margin (Yr)",
        "metric_short": "Gross Margin (Yr)",
        "datatype": "%",
        "statement": "Profitability"
    },
    {
        "metric_full": "Return on Equity (Yr)",
        "metric_short": "ROE (Yr)",
        "datatype": "%",
        "statement": "Management Effectiveness"
    },
    {
        "metric_full": "Revenue Growth (YoY)",
        "metric_short": "Rev Growth (YoY)",
        "datatype": "%",
        "statement": "Growth Ratios"
    }
]