Searching through thousands of securities to find a group matching a certain set of conditions can seem like a daunting task. We've created a new version of our Securities Screener to make that process as easy as possible.

What is the Intrinio Securities Screener?

The Securities Screener uses the Intrinio API to allow developers to sift through securities and return only those securities that meet a set of predefined parameters. The Securities Screener tool is more complex than a traditional API endpoint in that it uses complex logic in the request body to determine which securities are returned.

Using the Securities Screener requires some programming knowledge and is intended for use by developers. We offer several SDKs in various languages to make calling our API even easier.

Accessing the Securities Screener

To access the Securities Screener endpoint you will need an Intrinio access key. To create an access key, visit https://account.intrinio.com/login to set up an Intrinio account. An access key will automatically be generated for you upon creation of your account and can be found here

You can use your "sandbox" access key to test a variety of API endpoints in our sandbox environment; providing you with a large variety of free, limited data which you can use for developing, testing, and experimenting.

With access to Intrinio data, you can use the Securities Screener to sort through thousands of securities using hundreds of parameters including anything from a balance sheet or income statement to valuation metrics like EBITA and P/E. The Securities Screener can be used via curl or one of our SDKs.

Securities Screener via Web API

You can view the standard documentation for the APIv2 Securities Screener here, or you can read the dedicated screener documentation for a more in depth explanation. The Securities Screener API accepts a POST request body in JSON format containing the logical conditions you wish to screen with.

Start with the screener base endpoint and your api key as a parameter:
https://api-v2.intrinio.com/securities/screen?api_key={YOUR_API_KEY}

Next, build your POST request body JSON. Each request body has an operator property and a clauses  array. The operator property specifies logic to apply between clause conditions. Valid operator values are AND , OR , and NOT . The clause  array accepts objects with the following properties: field , operator , and value . These properties specify which field and value conditions to filter by.

For example, if you would like to return securities with a market capitalization greater than 1,000,000,000 and a price-to-earnings less than 3, your request body would be as follows:

{
  "operator": "AND",
  "clauses": [
    {
      "field": "marketcap",
      "operator": "gt",
      "value": "1000000000"
    },
    {
      "field": "pricetoearnings",
      "operator": "lt",
      "value": "3"
    }
  ]
}


The AND operator assures that both conditions are met by the security while the clauses describe the conditions. Here, lt represents "less than" and gt represents "greater than".

Using curl:

curl -XPOST -H 'api_key: YOUR_API_KEY' -H "Content-type: application/json" -d '{
  "operator": "AND",
  "clauses": [
    {
      "field": "marketcap",
      "operator": "gt",
      "value": "1000000000"
    },
    {
      "field": "pricetoearnings",
      "operator": "lt",
      "value": "3"
    }
  ]
}' 'https://api-v2.intrinio.com/securities/screen?order_column=marketcap&order_direction=asc'


The JSON response will contain an array of the applicable securities with info about that security as well as the values of the fields specified in the clauses array.

Sample Response

[
  {
    "security": {
      "id": "sec_2zvV8z",
      "company_id": "com_mgw1wz",
      "stock_exchange_id": "sxg_ozMr9y",
      "name": "Carrizo Oil & Gas, Inc.",
      "code": null,
      "currency": null,
      "ticker": "CRZO",
      "composite_ticker": "CRZO:US",
      "figi": "BBG000BXZFS2",
      "composite_figi": null,
      "share_class_figi": null
    },
    "data": [
      {
        "tag": "marketcap",
        "number_value": 1129654080,
        "text_value": null
      },
      {
        "tag": "pricetoearnings",
        "number_value": 2.2258,
        "text_value": null
      }
    ]
  },
]


Additionally, you can use the groups  clause to specify more groups of clauses, as shown below:

{
  "operator": "AND",
  "clauses": [
    {
      "field": "marketcap",
      "operator": "gt",
      "value": "1000000000"
    }
  ],
  "groups": [
    {
      "operator": "NOT",
      "clauses": [
        {
          "field": "pricetoearnings",
          "operator": "gt",
          "value": "5"
        },
        {
          "field": "marketcap",
          "operator": "gt",
          "value": "2000000000"
        }
      ]
    }
  ]
}


This POST request body will give you securities with a market capitalization greater than 1,000,000,000 but less than 2,000,000,000 and where their price-to-earnings is less than 5.

Securities Screener using the Intrinio Ruby SDK

Intrinio offers SDKs for several popular languages that allow for seamless integration into your app. You can view the Intrinio Ruby SDK here

Let's say you want to return a list of securities that meet the following conditions:

  • Is in the Healthcare, Services, or Financial sector
  • Has more than 100,000 employees
  • Is not in the state of California
  • Is only a primary security

First, you will need to install and require the intrinio-sdk gem and configure your authorization.

From the command-line:

gem install bundler
gem install intrinio-sdk
gem install awesome_print


In your main program file:

# Load the gem
require 'bundler/setup'
require 'intrinio-sdk'
require 'awesome_print'

# Setup authorization
Intrinio.configure do |config|
  config.api_key['api_key'] = 'YOUR_API_KEY'
end


Next, initialize the Intrinio Securities API and define the conditions:

security_api = Intrinio::SecurityApi.new

sectors = [
  'Healthcare',
  'Services',
  'Financial'
]

opts = {
  logic: Intrinio::SecurityScreenGroup.new(
    operator: "AND",
    clauses: [
      # Employees > 100,000
      Intrinio::SecurityScreenClause.new(
        field: "employees",
        operator: "gt",
        value: 100_000,
      )
    ],
    groups: [
      # In any of the sectors
      Intrinio::SecurityScreenGroup.new(
        operator: "OR",
        clauses: sectors.map {|sector|
          Intrinio::SecurityScreenClause.new(
            field: "sector",
            operator: "eq",
            value: sector,
          )
        },
      ),
      # Not in the state of California
      Intrinio::SecurityScreenGroup.new(
        operator: "NOT",
        clauses: [
          Intrinio::SecurityScreenClause.new(
            field: "state",
            operator: "eq",
            value: "California",
          )
        ],
      ),
    ]
  ),
  order_column: "employees",
  order_direction: "desc",
  primary_only: true,
}


Finally, make the API call with the options you've defined and print out the result.

begin
  results = security_api.screen_securities(opts)
  results.each do |result|
    ap result
  end
rescue Intrinio::ApiError => e
  puts "Exception when calling SecurityApi->screen_securities: #{e}"
end


The response will contain a list of securities that fit these parameters in descending order by employee size. The full code for this example can be found here.

If you replace the opts variable in the previous example with the following code, you will receive a list of primary securities with a market capitalization greater than 50 million and a price-to-earnings less than 3 in descending order by market capitalization.

opts = { 
  logic: Intrinio::SecurityScreenGroup.new(
    operator: "AND",
    clauses: [
      # Marketcap >= $50m
      Intrinio::SecurityScreenClause.new(
        field: "marketcap",
        operator: "gte",
        value: 50_000_000,
      ),
      # PE < 3
      Intrinio::SecurityScreenClause.new(
        field: "pricetoearnings",
        operator: "lt",
        value: 3,
      )
    ]
  ),
  order_column: "marketcap",
  order_direction: "desc",
  primary_only: true,
}


With the use of operators, clauses, and groups you can be as general or specific as you'd like when filtering for securities. In addition to Ruby, we currently support JavaScript, Python, Java, and C# SDKs.

Why Use Intrinio?

Unlike big data providers, Intrinio doesn't bundle data feeds into an expensive monthly subscription. In fact, many of its feeds are included in the sandbox environment and others include redistribution at prices that are disruptively affordable.

Unlike smaller data providers, Intrinio only has one API. This means you can subscribe to the data feeds you need while still using a single API or Excel syntax rather than a different syntax for each provider.

This simplicity and cost structure is designed to make financial data easy to access and affordable for fintech developers and financial analysts. That's our mission and the stock screener API is just another way we are increasing affordable access.

Did this answer your question?