What is the security screening and why does it use a POST request?

Screen securities allows you to filter the securities you receive by logic you set yourself. As explained in our screener documentation, the construction of operators, clauses, and fields make up the logic that hones down the data to a more manageable and relevant set that is easier to work with. The screen securities endpoint can be used in any of our SDKs, as well as the Web API and CSV download. 

The POST method is not conducive to in-browser data evaluation using the URL web API access, but there is good reason for its use. POST is mostly used in RESTful APIs as a data addition and modification method that allows the creation of data subsections. Thus the POST method is able to parse JSON formatting, which enables it to use logic to sort data by its contents. Intrinio utilizes this functionality of the method while preventing data modification to enable fast, clean retrieval of data that meets logistic criteria. 

Our API Explorer enables you to sample the data and some of the possible parameters within the website using either your sandbox or production keys, and gives you the URL created using those parameters. The POST method is performed directly on the page and the output is shown directly below.

Use cases for security screening: supported SDKs 

The following code snippets are examples of how to format the logic parameter and can be placed into a security screen program to filter the response. The language and description indicate where to place the logic in the sample programs. In every example, a request is being made to find securities where,

the total common equity = 100000000
or
the next earning year is 2017.

Javascript - after defining logic in the opts section of the program

var intrinioSDK = require('intrinio-sdk');
intrinioSDK.ApiClient.instance.authentications['ApiKeyAuth'].apiKey = "YOUR_API_KEY";

var securityAPI = new intrinioSDK.SecurityApi();
var opts = {
  'logic': new intrinioSDK.SecurityScreenGroup(),
  'orderColumn': "name",
  'orderDirection': "asc",
  'primaryOnly': false,
  'pageSize': 100
};

var clause1 = new intrinioSDK.SecurityScreenClause();
clause1.field = "totalcommonequity";
clause1.operator = "gt";
clause1.value = 100000000;

var clause2 = new intrinioSDK.SecurityScreenClause();
clause2.field = "next_earnings_year";
clause2.operator = "eq";
clause2.value = 2017;

opts.logic.operator = "OR";
opts.logic.clauses =[clause1, clause2];

securityAPI.screenSecurities(opts).then(function(data) {
  console.log(data);
}, function(error) {
  console.error(error);
});

Python - logic

from __future__ import print_function
import time
import intrinio_sdk
from intrinio_sdk.rest import ApiException
from pprint import pprint

intrinio_sdk.ApiClient().configuration.api_key['api_key'] = 'YOUR_API_KEY'

security_api = intrinio_sdk.SecurityApi()

clause1 = intrinio_sdk.SecurityScreenClause(
  field ='totalcommonequity',
  operator = 'gt',
  value = 100000000
)

clause2 = intrinio_sdk.SecurityScreenClause(
  field = 'next_earnings_year',
  operator = 'eq',
  value = 2017
)

logic = intrinio_sdk.SecurityScreenGroup(operator ="OR", clauses =[clause1, clause2])
order_column = 'name'
order_direction = 'asc'
primary_only = False
page_size = 100

try:
  api_response = security_api.screen_securities(
      logic=logic,
      order_direction=order_direction,
      primary_only=primary_only,  
      page_size=page_size,
  )
  pprint(api_response)
 
except ApiException as e:
  print("Exception when calling SecurityApi->screen_securities: %s\r\n" % e)

Java - logic (added after logic defined as a new security screen group)

import java.util.List;
import com.intrinio.api.*;
import com.intrinio.invoker.*;
import com.intrinio.invoker.auth.*;
import com.intrinio.models.*;

public class yourClass {
  public static void main(String[] args) {

    ApiClient defaultClient = Configuration.getDefaultApiClient();
    ApiKeyAuth auth = (ApiKeyAuth) defaultClient.getAuthentication("ApiKeyAuth");
    auth.setApiKey("YOUR_API_KEY");

    SecurityApi securityApi = new SecurityApi();

      SecurityScreenGroup logic = new SecurityScreenGroup(); // SecurityScreenGroup | The logic to screen with, consisting of operators, clauses, and nested groups.<br/> See <a href=\"/documentation/screener_v2\" target=\"_blank\">screener documentation</a> for details on how to construct conditions.
      String orderColumn = null; // String | Results returned sorted by this column
      String orderDirection = "asc"; // String | Sort order to use with the order_column
      Boolean primaryOnly = false; // Boolean | Return only primary securities
      Integer pageSize = 100; // Integer | The number of results to return. Maximum for this endpoint is 50000.

      logic.setOperator("OR");

      SecurityScreenClause clause1 = new SecurityScreenClause();
      clause1.setField("totalcommonequity");
      clause1.setOperator(SecurityScreenClause.OperatorEnum.GT);
      clause1.setValue("100000000");
      logic.addClausesItem(clause1);

      SecurityScreenClause clause2 = new SecurityScreenClause();
      clause2.setField("next_earnings_year");
      clause2.setOperator(SecurityScreenClause.OperatorEnum.EQ);
      clause2.setValue("2017");
      logic.addClausesItem(clause2);

      try{
      List<SecurityScreenResult> result = securityApi.screenSecurities(logic, orderColumn, orderDirection, primaryOnly, pageSize);
        System.out.println(result);

    } catch (ApiException e) {
      System.err.println("Exception when calling SecurityApigetSecurityStockPrices");
      e.printStackTrace();
    }
  }

Ruby - logic

require 'intrinio-sdk'
require 'pp'

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

security_api = Intrinio::SecurityApi.new

opts = {
  logic: Intrinio::SecurityScreenGroup.new(),
  order_column: "name",
  order_direction: "asc",
  primary_only: false,
  page_size: 100
}

clause_1 = Intrinio::SecurityScreenClause.new()
clause_1.field = 'totalcommonequity'
clause_1.operator= 'gt'
clause_1.value= 100000000

clause_2 =Intrinio::SecurityScreenClause.new()
clause_2.field = 'next_earnings_year'
clause_2.operator= 'eq'
clause_2.value= 2017

logic_Group = Intrinio::SecurityScreenGroup.new()
logic_Group.operator= "OR"
logic_Group.clauses=[clause_1, clause_2]

opts_Update = {logic: logic_Group}
opts.merge!(opts_Update)

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

C# - logic

using System;
using Intrinio.SDK.Api;
using Intrinio.SDK.Client;
using Intrinio.SDK.Model;

namespace YourNameSpace
{
    public class ScreenSecuritiesExample
    {
        public static void Main()
        {
            Configuration.Default.AddApiKey("api_key", "YOUR_API_KEY");

            SecurityScreenClause clause1 = new SecurityScreenClause
                (
                _Operator: SecurityScreenClause.OperatorEnum.Gt,
                Field: "totalcommonequity",
                Value: "100000000"
                );
               
            SecurityScreenClause clause2 = new SecurityScreenClause
                (
                _Operator: SecurityScreenClause.OperatorEnum.Eq,
                Field: "next_earnings_year",
                Value: "2017"
                );

            System.Collections.Generic.List<SecurityScreenClause> clauses = new System.Collections.Generic.List<SecurityScreenClause> ();
            clauses.Add(clause1);
            clauses.Add(clause2);

            var securityApi = new SecurityApi();
            var logic = new SecurityScreenGroup(_Operator: "OR", Clauses: clauses);
            var orderColumn = "name";  
            var orderDirection = "asc";  
            var primaryOnly = true;  
            var pageSize = 100;  

            try
            {
                var result = securityApi.ScreenSecurities(logic, orderColumn, orderDirection, primaryOnly, pageSize);

                foreach (SecurityScreenResult results in result)
                {
                    Console.Write(results);
                }
            }
           
            catch (Exception e)
            {
                Console.WriteLine("Exception when calling SecurityApi.ScreenSecurities: " + e.Message);
            }
        }
    }
}

Use cases for security screening: web API using Postman

Postman makes any type of HTTP request easy with its customization options. Since screen securities uses the POST method to parse a JSON body to format the query, all that's needed is to change the request type and input the parameters to the request body.

Changing the request type in Postman with:

https://api-v2.intrinio.com/securities/screen?api_key=YOUR_API_KEY
{
    "operator": "OR",
    "clauses": [
        {
            "field": "totalcommonequity",
            "operator": "gt",
            "value": "1000000000"
        },
        {
            "field": "next_earnings_year",
            "operator": "eq",
            "value": "2017"
        }
    ]
}

Use cases for security screening: bulk download

CSV download

https://api.intrinio.com/securities/search.csv?conditions=totalcommonequity~gt~1000000000,next_earnings_year~eq~2017&api_key=YOUR_API_KEY

Conclusion

The variety of information that securities cover makes the use of logical selection versatile. If you need help with tag information, our customer success team would be happy to help you find what you're looking for. If you run into access issues, you can submit a ticket or ask the community for help on the community forum.


Did this answer your question?