Skip to main content

Screening Requests

This page explains in more detail how the screening request works.

There are two endpoints for screening. One for screening crypto and one for screening stocks:

  • screening stocks endpoint: POST request to https://api.tickflow.io/v1/stocks/screener.
  • screening crypto endpoint: POST request to https://api.tickflow.io/v1/crypto/screener.

Both the stock screening and crypto screening endpoints have the same request schemas. Both screening endpoint takes body parameters in the form of a JSON.

They only differ in the data fields they allow. For example, the addresses_count field is exclusive to crypto, while the peg_ratio field is exclusive to stocks.

The JSON must adhere to the following schema:

{
    "fields": [ "string1", "string2", "..." ], 
    "filters": [
        {
            "field": "string" ,
            "comparator": "string",
            "threshold": "float/string"
        },
        {
            "field": "string" ,
            "comparator": "string",
            "threshold": "float/string"
        }
    ],
    "sort_by": "string" # OPTIONAL
}

You can find additional information about the endpoints in the API Reference.

Understanding The Request Parameters​

Fields​

fields is a list of strings, where each string is a stock field or crypto field we want to query data for or use in our screening.

Filters​

filters is a list of objects/dictionaries, where each object represents a filter for screening. Each filter must have 3 properties: field, comparator, threshold.

  1. field is the property of the stock we want to compare for filtering. For example, if we want to look at stocks with prices greater than $10. The field should be price. You can find the full list of fields for stocks and crypto in the Data Reference.
  2. comparator is either >, < or =. The comparator compares the field to the threshold.
  3. threshold is the limit at which the stock's field passes our filter when using the comparator.

Sort By​

sort_by is an optional string which is used to sort the result by a field. Currently, only ascending sorts are available. By default, results are sorted alphabetically. Note: The field chosen for sorting must also be in the fields list or you will receive a 422 error.

An Example Request Body​

In this example request, we query for the following data fields:

  • sector
  • dividend_yield
  • day_close

And then we apply the two screening filters.

  • stocks with dividend yield greather than 0
  • stocks witn day_low less than 10

{
    "fields": ["sector", "dividend_yield", "day_close"],
    "filters": [ 
                {
                    "field": "dividend_yield",
                    "comparator": ">",
                    "threshold": 0
                },
                {
                    "field": "day_close",
                    "comparator": "<",
                    "threshold": 10
                }
            ]
}