# Stock Screener

`GET` `https://api.unusualwhales.com/api/screener/stocks`

A stock screener endpoint to screen the market for stocks by a variety of filter options.

For an example of what can be build with this endpoint check out the [Stock Screener](https://unusualwhales.com/flow/ticker_flows)
on UnusualWhales.


## Authentication

```
Authorization: Bearer YOUR_API_KEY
```

## Query Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `ticker` | Ticker | No | A comma separated list of tickers. To exclude certain tickers prefix the first ticker with a `-`. |
| `issue_types[]` | Issue types | No | An array of 1 or more issue types. |
| `min_change` | string | No | The minimum % change to the previous trading day. |
| `max_change` | string | No | The maximum % change to the previous trading day. |
| `min_underlying_price` | string | No | The minimum stock price. |
| `max_underlying_price` | string | No | The maximum stock price. |
| `is_s_p_500` | boolean | No | Boolean whether to only include stocks which are part of the S&P 500. Setting this to false has no effect. |
| `has_dividends` | boolean | No | Boolean wheter to only include stocks which pay dividends. Setting this to false has no effect. |
| `sectors[]` | Sectors | No | An array of 1 or more sectors. |
| `min_marketcap` | string | No | The minimum marketcap. |
| `max_marketcap` | string | No | The maximum marketcap. |
| `min_perc_3_day_total` | string | No | The minimum ratio of options volume vs 3 day avg options volume. |
| `max_perc_3_day_total` | string | No | The maximum ratio of options volume vs 3 day avg options volume. |
| `min_perc_3_day_call` | string | No | The minimum ratio of call options volume vs 3 day avg call options volume. |
| `max_perc_3_day_call` | string | No | The maximum ratio of call options volume vs 3 day avg call options volume. |
| `min_perc_3_day_put` | string | No | The minimum ratio of put options volume vs 3 day avg put options volume. |
| `max_perc_3_day_put` | string | No | The maximum ratio of put options volume vs 3 day avg put options volume. |
| `min_perc_30_day_total` | string | No | The minimum ratio of options volume vs 30 day avg options volume. |
| `max_perc_30_day_total` | string | No | The maximum ratio of options volume vs 30 day avg options volume. |
| `min_perc_30_day_call` | string | No | The minimum ratio of call options volume vs 30 day avg call options volume. |
| `max_perc_30_day_call` | string | No | The maximum ratio of call options volume vs 30 day avg call options volume. |
| `min_perc_30_day_put` | string | No | The minimum ratio of put options volume vs 30 day avg put options volume. |
| `max_perc_30_day_put` | string | No | The maximum ratio of put options volume vs 30 day avg put options volume. |
| `min_total_oi_change_perc` | string | No | The minimum open interest change compared to the previous day. |
| `max_total_oi_change_perc` | string | No | The maximum open interest change compared to the previous day. |
| `min_call_oi_change_perc` | string | No | The minimum open interest change of call contracts compared to the previous day. |
| `max_call_oi_change_perc` | string | No | The maximum open interest change of call contracts compared to the previous day. |
| `min_put_oi_change_perc` | string | No | The minimum open interest change of put contracts compared to the previous day. |
| `max_put_oi_change_perc` | string | No | The maximum open interest change of put contracts compared to the previous day. |
| `min_implied_move` | string | No | The minimum implied move. |
| `max_implied_move` | string | No | The maximum implied move. |
| `min_implied_move_perc` | string | No | The minimum implied move perc. |
| `max_implied_move_perc` | string | No | The maximum implied move perc. |
| `min_volatility` | string | No | The minimum volatility. |
| `max_volatility` | string | No | The maximum volatility. |
| `min_iv_rank` | string | No | The minimum iv rank. |
| `max_iv_rank` | string | No | The maximum iv rank. |
| `min_volume` | integer | No | The minimum options volume. |
| `max_volume` | integer | No | The maximum options volume. |
| `min_call_volume` | integer | No | The minimum call options volume. |
| `max_call_volume` | integer | No | The maximum call options volume. |
| `min_put_volume` | integer | No | The minimum put options volume. |
| `max_put_volume` | integer | No | The maximum put options volume. |
| `min_premium` | string | No | The minimum options premium. |
| `max_premium` | string | No | The minimum options premium. |
| `min_call_premium` | string | No | The minimum call options premium. |
| `max_call_premium` | string | No | The minimum call options premium. |
| `min_put_premium` | string | No | The minimum put options premium. |
| `max_put_premium` | string | No | The minimum put options premium. |
| `min_net_premium` | string | No | The minimum net options premium. |
| `max_net_premium` | string | No | The minimum net options premium. |
| `min_net_call_premium` | string | No | The minimum net call options premium. |
| `max_net_call_premium` | string | No | The maximum net call options premium. |
| `min_net_put_premium` | string | No | The minimum net put options premium. |
| `max_net_put_premium` | string | No | The maximum net put options premium. |
| `min_oi` | integer | No | The minimum open interest. |
| `max_oi` | integer | No | The maximum open interest. |
| `min_oi_vs_vol` | string | No | The minimum open interest vs options volume ratio. |
| `max_oi_vs_vol` | string | No | The maximum open interest vs options volume ratio. |
| `min_put_call_ratio` | string | No | The minimum put to call ratio. |
| `max_put_call_ratio` | string | No | The maximum put to call ratio. |
| `order` | Screener order by field | No | The field to order by. |
| `order_direction` | OrderDirection | No | Whether to sort descending or ascending. Descending by default. |
| `min_stock_volume_vs_avg30_volume` | string | No | The minimum stock volume vs average 30 day volume. |
| `max_avg30_volume` | string | No | The maximum stock volume vs average 30 day volume. |
| `date` | Optional Market Date | No | A trading date in the format of YYYY-MM-DD.
This is optional and by default the last trading date.
 |


## Response (200)

| Field | Type | Description |
|-------|------|-------------|
| `avg_30_day_call_volume` | Market General Avg 30 Day Call Volume | Avg 30 day call volume. |
| `avg_30_day_put_volume` | Market General Avg 30 Day Put Volume | Avg 30 day put volume. |
| `avg_3_day_call_volume` | Market General Avg 3 Day Call Volume | Avg 3 day call volume. |
| `avg_3_day_put_volume` | Market General Avg 3 Day Put Volume | Avg 3 day put volume. |
| `avg_7_day_call_volume` | Market General Avg 7 Day Call Volume | Avg 7 day call volume. |
| `avg_7_day_put_volume` | Market General Avg 7 Day Put Volume | Avg 7 day put volume. |
| `bearish_premium` | Market General Bearish Premium | The bearish premium is defined as (call premium bid side) + (put premium ask side). |
| `bullish_premium` | Market General Bullish Premium | The bullish premium is defined as (call premium ask side) + (put premium bid side). |
| `call_open_interest` | Market General Call Open Interest | The sum of open interest of all the call options. |
| `call_premium` | Market General Call Premium | The sum of the premium of all the call transactions that executed. |
| `call_volume` | Market General Call Volume | The sum of the size of all the call transactions that executed. |
| `call_volume_ask_side` | Market General Call Volume Ask Side | The sum of the size of all the call transactions that executed on the ask side. |
| `call_volume_bid_side` | Market General Call Volume Bid Side | The sum of the size of all the call transactions that executed on the bid side. |
| `close` | Stock Close Price | The close stock price of the ticker. |
| `er_time` | Stock Earnings time | The time when the earnings will be released. |
| `implied_move` | Stock Implied Move | The implied move of the underlying stock by a given date based on the money option contracts. It is calculated by multiplying the sum of the call and put price by 0.85. If no expiry date is included, then the implied move is for the nearest end of the week expiration (the nearest monthly expiration if there are no weekly contracts). |
| `implied_move_perc` | Stock Implied Move Perc | The implied move as a percentage of the underlying stock price. |
| `is_index` | Stock Is Index Ticker | Indicator, whether the ticker is an index. |
| `issue_type` | Stock Issue Type | The issue type of the ticker. |
| `iv30d` | Stock IV 30d | The 30 day implied volatility. |
| `iv30d_1d` | Stock IV 30d 1D | The previous trading day's 30 day implied volatility. |
| `iv30d_1m` | Stock IV 30d 1M | The implied volatility relative to the implied volatility throughout the previous year. A rank of 0 indicates that the implied volatility is the lowest it has been within the past year. A rank of 100 indicates that the implied volatility is the highest it has been within the past year. |
| `iv30d_1w` | Stock IV 30d 1W | The 30 day implied volatility from 1 week ago. |
| `iv_rank` | Stock IV 30d 1M | The implied volatility relative to the implied volatility throughout the previous year. A rank of 0 indicates that the implied volatility is the lowest it has been within the past year. A rank of 100 indicates that the implied volatility is the highest it has been within the past year. |
| `marketcap` | Stock Marketcap AUM | The marketcap of the underlying ticker. If the issue type of the ticker is ETF then the marketcap represents the AUM. |
| `net_call_premium` | Market General Net Call Premium | Defined as (call premium ask side) - (call premium bid side). |
| `net_put_premium` | Market General Net Put Premium | Defined as (put premium ask side) - (put premium bid side). |
| `next_dividend_date` | Stock Next Dividend Date | The next dividend date of the ticker. Null if either unknown as of now or the stock does not pay dividends. |
| `next_earnings_date` | Stock Next Earnings Date | The next earnings date of the ticker. Null if either unknown as of now or if the ticker does not have any earnings such as an ETF |
| `prev_call_oi` | Market General Previous Call Open interest | The call open interest of the previous trading day. |
| `prev_close` | Stock Prev Close Price | The previous trading day's stock price of the ticker. |
| `prev_put_oi` | Market General Previous Put Open interest | The put open interest of the previous trading day. |
| `put_call_ratio` | Market General Put Call Ratio | The put call ratio which is defined as put volume / call volume. |
| `put_open_interest` | Market General Put Open Interest | The sum of the open interest of all the put options. |
| `put_premium` | Market General Put Premium | The sum of the premium of all the put transactions that executed. |
| `put_volume` | Market General Put Volume | The sum of the size of all the put transactions that executed. |
| `put_volume_ask_side` | Market General Put Volume Ask Side | The sum of the size of all the put transactions that executed on the ask side. |
| `put_volume_bid_side` | Market General Put Volume Bid Side | The sum of the size of all the put transactions that executed on the bid side. |
| `relative_volume` | Stock Relative Volume | The relative volume of the stock. The volume traded today divided by the average volume over the last 30 days. |
| `sector` | Market General Sector | The financial sector of the ticker. Empty if unknown or not applicable such as ETF/Index. |
| `ticker` | Stock Ticker | The stock ticker. |
| `total_open_interest` | Stock Total Open Interest | The sum of open interest of all chains for the given ticker. |
| `volatility` | Stock Volatility | The implied volatility average of the at the money put and call option contracts. If no expiry date is included, then the volatility is of the nearest end of the week expiration (the nearest monthly expiration if there are no weekly contracts). |
| `week_52_high` | Stock Week 52 High | The 52 week high stock price of the ticker. |
| `week_52_low` | Stock Week 52 low | The 52 week low stock price of the ticker. |


## Example

### curl

```bash
curl -X GET "https://api.unusualwhales.com/api/screener/stocks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"
```

### Python

```python
import http.client

conn = http.client.HTTPSConnection("api.unusualwhales.com")
headers = {"Authorization": "Bearer YOUR_API_KEY", "Accept": "application/json"}
conn.request("GET", "/api/screener/stocks", headers=headers)
response = conn.getresponse()
print(response.read().decode("utf-8"))
```

## Response Example

```json
{
  "data": [
    {
      "bullish_premium": "143198625",
      "put_open_interest": 3564153,
      "put_volume_bid_side": 314160,
      "call_volume_bid_side": 498271,
      "prev_call_oi": 3994750,
      "put_call_ratio": "0.815713920982337",
      "call_volume_ask_side": 417251,
      "iv30d_1d": "0.18791808187961578",
      "ticker": "AAPL",
      "implied_move_perc": "0.012247398860706955",
      "call_open_interest": 3975333,
      "iv_rank": "13.52369891956068210400",
      "prev_put_oi": 3679410,
      "er_time": "unknown",
      "avg_3_day_put_volume": "388676.000000000000",
      "avg_3_day_call_volume": "679145.333333333333",
      "iv30d_1w": "0.18398597836494446",
      "put_volume_ask_side": 431791,
      "avg_30_day_put_volume": "436126.833333333333",
      "iv30d": "0.2038053572177887",
      "put_volume": 808326,
      "avg_30_day_call_volume": "606258.533333333333",
      "bearish_premium": "196261414",
      "next_dividend_date": null,
      "call_premium": "222941665",
      "avg_7_day_put_volume": "401961.285714285714",
      "week_52_low": "124.17",
      "put_premium": "163537151",
      "net_put_premium": "23924325",
      "relative_volume": "1.2247398860706955",
      "volatility": "0.18338055163621902",
      "net_call_premium": "-29138464",
      "next_earnings_date": "2023-10-26",
      "implied_move": "2.2398043036460877",
      "week_52_high": "198.23",
      "close": "182.91",
      "total_open_interest": 7539486,
      "is_index": false,
      "avg_7_day_call_volume": "679430.000000000000",
      "date": "2023-09-06",
      "call_volume": 990943,
      "iv30d_1m": "0.2136848270893097",
      "prev_close": "189.70",
      "sector": "Technology",
      "issue_type": "Common Stock",
      "marketcap": "2965813810400"
    }
  ]
}
```