Intrinio’s Security Screener lets you sift through securities and return those that meet predefined parameters through our simple API.
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. You can retrieve your key on your account page. If you're new to Intrinio, request a consultation to get started.
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 Securities Screener, 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. Here is the documentation for the Intrinio Ruby SDK.
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. Here is the full code for this example.
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, R, Java, and C# SDKs.