# Screen Stocks

`GET` `/v1/screener`

Run the same powerful stock screen that powers the Vantafin web screener, programmatically. Filter the US equity universe across 80+ metrics spanning security info, live market data, technicals, TTM financials, valuation multiples, margins & returns, growth rates and dividends. Each filter is a 'metric:operator:value' clause and clauses combine with AND - pass the filter parameter multiple times to stack conditions (e.g. filter=peRatio:below:20&filter=marketCap:above:1e9&filter=revenueGrowthYoy:above:25). Numeric metrics support above, below, above_or_equal, below_or_equal, equal, between and outside; categorical metrics (sector, industry, country, exchange) match an exact comma-separated list; text metrics (ticker, company) support equal and contains. Sort by any metric, page with limit/offset, and request extra metric columns. Percent metrics are returned in percent units (25 = 25%) and dollar metrics in dollars (1e9 = $1B). Call Screener Fields for the full metric catalogue.

## Use cases

- Building custom stock screens (value, growth, momentum, dividend) on your own schedule
- Quantitative research and factor backtests over the live universe
- Powering alerts when stocks cross fundamental or technical thresholds
- Generating watchlists and ranked tables for dashboards

## Input parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `filter` | string | No | Repeatable. A 'metric:operator:value' clause (e.g. peRatio:below:20). Numeric operators: above, below, above_or_equal, below_or_equal, equal, between (two values, e.g. price:between:10:50), outside. Categorical metrics (sector, industry, country, exchange) use 'equal' with a comma-separated list (e.g. sector:equal:Technology,Healthcare; country uses ISO-2 codes). Text metrics (ticker, company) accept 'equal' or 'contains'. |
| `sort` | string | No | Metric id to sort by (default marketCap). |
| `order` | string | No | Sort direction: asc or desc (default desc). |
| `columns` | string | No | Comma-separated extra metric ids to include in each row. |
| `limit` | integer | No | Page size, 1-100 (default 50). |
| `offset` | integer | No | Row offset for pagination (default 0). |

## Output parameters

| Name | Type | Description |
| --- | --- | --- |
| `results` | array | Matching rows for this page, in sort order. |
| `results[].ticker` | string | Ticker symbol. |
| `results[].company` | string | Company name. |
| `results[].sector` | string | GICS sector. |
| `results[].marketCap` | number | Market capitalization (USD). Plus any other requested metric columns keyed by metric id. |
| `count` | integer | Number of rows in this response. |
| `total` | integer | Total number of stocks matching the filters. |
| `limit` | integer | Page size applied. |
| `offset` | integer | Row offset applied. |
| `sort` | string | Metric id the results were sorted by. |
| `order` | string | Sort direction: asc or desc. |
| `columns` | array | Metric ids present in each result row. |
| `filters` | array | The parsed filters that were applied (metric, op, values). |

## Example response

```json
{
  "results": [
    {
      "ticker": "AAPL",
      "company": "Apple Inc.",
      "sector": "Technology",
      "industry": "Consumer Electronics",
      "country": "US",
      "exchange": "NASDAQ",
      "price": 248.5,
      "changeAbs": 1.32,
      "changePct": 0.53,
      "volume": 41200000,
      "usdVolume": 10238200000,
      "marketCap": 3760000000000,
      "peRatio": 19.4,
      "roe": 154.2
    },
    {
      "ticker": "MSFT",
      "company": "Microsoft Corporation",
      "sector": "Technology",
      "industry": "Software - Infrastructure",
      "country": "US",
      "exchange": "NASDAQ",
      "price": 432.1,
      "changeAbs": -2.1,
      "changePct": -0.48,
      "volume": 18900000,
      "usdVolume": 8166690000,
      "marketCap": 3210000000000,
      "peRatio": 18.1,
      "roe": 34.6
    }
  ],
  "count": 2,
  "total": 18,
  "limit": 25,
  "offset": 0,
  "sort": "marketCap",
  "order": "desc",
  "columns": [
    "ticker",
    "company",
    "sector",
    "industry",
    "country",
    "exchange",
    "price",
    "changeAbs",
    "changePct",
    "volume",
    "usdVolume",
    "marketCap",
    "peRatio",
    "roe"
  ],
  "filters": [
    {
      "metric": "sector",
      "op": "equal",
      "values": [
        "Technology"
      ]
    },
    {
      "metric": "peRatio",
      "op": "below",
      "values": [
        20
      ]
    },
    {
      "metric": "marketCap",
      "op": "above",
      "values": [
        1000000000
      ]
    }
  ]
}
```

## Examples

### cURL

```bash
curl "https://api.vantafin.com/v1/screener?filter=sector:equal:Technology&filter=peRatio:below:20&filter=marketCap:above:1e9&sort=marketCap&columns=peRatio,roe&apiKey=$VANTAFIN_API_KEY"
```

### Python

```python
from vantafin import RESTClient

client = RESTClient("vf-live-your_api_key")

result = client.screener(filter=["sector:equal:Technology", "peRatio:below:20", "marketCap:above:1e9"], sort="marketCap", columns="peRatio,roe", limit=25)

print(result)
```

### JavaScript

```javascript
import { RestClient } from "vantafin";

const client = new RestClient("vf-live-your_api_key");

const result = await client.screener({ filter: ["sector:equal:Technology", "peRatio:below:20", "marketCap:above:1e9"], sort: "marketCap", columns: "peRatio,roe", limit: 25 });

console.log(result);
```

### Go

```go
package main

import (
	"fmt"
	"log"

	"github.com/vantafin/vantafin-go"
)

func main() {
	client := vantafin.NewClient("vf-live-your_api_key")

	result, err := client.Screener(vantafin.Params{"filter": []string{"sector:equal:Technology", "peRatio:below:20", "marketCap:above:1e9"}, "sort": "marketCap", "columns": "peRatio,roe", "limit": 25})
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(result)
}
```

### Java

```java
import com.vantafin.RestClient;
import com.vantafin.Params;
import java.util.List;

public class Example {
    public static void main(String[] args) throws Exception {
        RestClient client = new RestClient("vf-live-your_api_key");

        Object result = client.screener(Params.of().set("filter", List.of("sector:equal:Technology", "peRatio:below:20", "marketCap:above:1e9")).set("sort", "marketCap").set("columns", "peRatio,roe").set("limit", 25));

        System.out.println(result);
    }
}
```

### Ruby

```ruby
require "vantafin"

client = Vantafin::RestClient.new("vf-live-your_api_key")

result = client.screener(filter: ["sector:equal:Technology", "peRatio:below:20", "marketCap:above:1e9"], sort: "marketCap", columns: "peRatio,roe", limit: 25)

pp result
```