Screening

Screening

The screener is incredibly versatile, you can index anything but for the purpose of this documentation we will focus on indexing stocks.

To enable the stock screener you need to add two endpoints to your server: one endpoint that returns a list of the metrics you want to use in the screener and another endpoint that returns a list of companies for a specified criteria.

Metrics Endpoint

The endpoint should return a list of metrics with the following fields: name, id, category (optional), format, isCurrency, example, and description. You can use our endpoint to retrieve a description and example range for each metric.

Note: The format field should be: number, ratio, %, or string.

[
{
"name": "Country",
"id": "country",
"format": "string",
"isCurrency": false,
"example": [
"US",
"CA"
],
"description": "Country is the country in which a company is headquartered.",
"category": "Basic"
},
{
"name": "Market Cap",
"id": "marketCap",
"format": "number",
"isCurrency": true,
"type": "range",
"example": [
1000000,
1000000000
],
"description": "Market Cap, or Market Capitalization, is the total value of all a company's shares of stock, calculated by multiplying the share price by the number of shares outstanding.",
"category": "Valuation"
},
{
"name": "P/E",
"id": "peRatio",
"format": "ratio",
"isCurrency": false,
"example": [
0,
30
],
"description": "The P/E Ratio, or Price-to-Earnings Ratio, is a financial metric that measures the market value per share divided by the earnings per share, used to determine if a stock is over or underpriced.",
"category": "Valuation"
},
{
"id": "epsForwardCagr2Y",
"name": "EPS Forward 2Y CAGR",
"format": "%",
"isCurrency": false,
"statement": "Ratios",
"example": [
-5,
25
],
"description": "EPS Forward 2Y CAGR (Earnings Per Share Forward 2 Year Compound Annual Growth Rate) is the projected annual growth rate of a company's earnings per share over the next two years, expressed as a percentage.",
"category": "Growth"
}
]

Query Endpoint

We will use our models to generate filters using those metrics, for example if a user asks: "Provide a list of North American companies below $100 billion in market cap, trading below 30 P/E, and expected to grow earnings by more than 15%." We would generate this JSON:

{
"country": [
"US",
"CA"
],
"marketCap": [
0,
100000000000
],
"epsForwardCagr2Y": [
15,
null
],
"peRatio": [
0,
30
]
}

We would then query your endpoint to retrieve a list of companies that match the criteria. The endpoint should return a list of companies with the following fields: name, ticker, logo (logo is optional - if left blank we will try to find the logo for you using either our database or company website favicon), and the metrics filtered by the query. Example of what the endpoint should return:

[
{
"name": "Schlumberger Limited",
"ticker": "SLB",
"country": "US",
"logo": "https://finchat.io/assets/logos/301966.png",
"currency": "USD",
"marketCap": 82420019444,
"peRatio": 21.18705387842522,
"epsForwardCagr2Y": 30.0503
},
{
"name": "PayPal Holdings, Inc.",
"ticker": "PYPL",
"country": "US",
"logo": "https://finchat.io/assets/logos/112732.png",
"currency": "USD",
"marketCap": 67715970835.99999,
"peRatio": 17.19499858915692,
"epsForwardCagr2Y": 17.0842
},
{
"name": "FedEx Corporation",
"ticker": "FDX",
"country": "US",
"logo": "https://finchat.io/assets/logos/124423.png",
"currency": "USD",
"marketCap": 64977711323,
"peRatio": 16.689276485788113,
"epsForwardCagr2Y": 20.8802
},
{
"name": "Marriott International, Inc.",
"ticker": "MAR",
"country": "US",
"logo": "https://finchat.io/assets/logos/31148.png",
"currency": "USD",
"marketCap": 60402462744,
"peRatio": 22.900794432437287,
"epsForwardCagr2Y": 18.8826
},
{
"name": "Thomson Reuters Corporation",
"ticker": "TRI",
"country": "CA",
"logo": "https://finchat.io/assets/logos/515275.png",
"currency": "USD",
"marketCap": 57588114359.69003,
"peRatio": 28.75401652315544,
"epsForwardCagr2Y": 18.0455
},
{
"name": "Target Corporation",
"ticker": "TGT",
"country": "US",
"logo": "https://finchat.io/assets/logos/174438.png",
"currency": "USD",
"marketCap": 56975962421,
"peRatio": 16.922034976501365,
"epsForwardCagr2Y": 22.8302
},
{
"name": "American International Group, Inc.",
"ticker": "AIG",
"country": "US",
"logo": "https://finchat.io/assets/logos/250388.png",
"currency": "USD",
"marketCap": 41197631240,
"peRatio": 8.949091776206828,
"epsForwardCagr2Y": 30.7643
},
{
"name": "Cheniere Energy, Inc.",
"ticker": "LNG",
"country": "US",
"logo": "https://finchat.io/assets/logos/374377.png",
"currency": "USD",
"marketCap": 39113303110,
"peRatio": 4.841566548054492,
"epsForwardCagr2Y": 44.5383
},
{
"name": "The Travelers Companies, Inc.",
"ticker": "TRV",
"country": "US",
"logo": "https://finchat.io/assets/logos/392856.png",
"currency": "USD",
"marketCap": 36820794612,
"peRatio": 17.059995218152185,
"epsForwardCagr2Y": 17.663
},
{
"name": "Rockwell Automation, Inc.",
"ticker": "ROK",
"country": "US",
"logo": "https://finchat.io/assets/logos/300504.png",
"currency": "USD",
"marketCap": 35497511123,
"peRatio": 25.216872858085512,
"epsForwardCagr2Y": 18.3592
}
]