get all expiries and contracts

We are tasked with collecting all contracts across the entire options montage for a heavily-traded name, MSTR in this example. Our first step is collecting all expiries via the stock/Volume & OI per Expiry endpoint:

https://api.unusualwhales.com/docs#/operations/PublicApi.TickerController.vol_oi_per_expiry

200, success! If we were to call vol_oi_rsp.json() we would get the following data:

>>> vol_oi_rsp.json()
{
    'data': [
        {'expires': '2025-01-31', 'oi': 438322, 'volume': 329297},
        {'expires': '2025-02-07', 'oi': 60345, 'volume': 44701},
        ...
        {'expires': '2027-06-17', 'oi': 0, 'volume': 293}
    ]
}

And for the time being we are only interested in the expiration dates, so we will collect those strings into a list:

Nice, our expiry_dates list now contains:

>>> expiry_dates
['2025-01-31', '2025-02-07', ... '2027-06-17']

We can use these values to loop through the option-contract/Option contracts endpoint, collecting observations as we go and paginating through responses til an empty json response occurs before moving on to the next expiry:

https://api.unusualwhales.com/docs#/operations/PublicApi.OptionContractController.option_contracts

I want to add the convenient YYYY-MM-DD date to each observations, which we could do by parsing it out of the option_symbol field, but since I intend on plotting this data (eventually) I will instead create polars DataFrames and add my convenience columns there.

We already know what the response looks like from this endpoint:

{
  "data": [
    {
      "ask_volume": 56916,
      "avg_price": "0.77927817593516586531",
      "bid_volume": 68967,
      "floor_volume": 1815,
      "high_price": "5.75",
      "implied_volatility": "0.542805337797143",
      "last_price": "0.01",
      "low_price": "0.01",
      "mid_volume": 6393,
      "multi_leg_volume": 9871,
      "nbbo_ask": "0.01",
      "nbbo_bid": "0",
      "no_side_volume": 6393,
      "open_interest": 22868,
      "option_symbol": "AAPL240202P00185000",
      "prev_oi": 20217,
      "stock_multi_leg_volume": 13,
      "sweep_volume": 12893,
      "total_premium": "10307980.00",
      "volume": 132276
    },
    ...
  ]
}

Cool, but maybe we want to aggregate in some other interesting ways, so let's add the expiry, page number (results are paginated, you will see in the while loop), strike price, and option type (call or put).

First, as an exercise, let's knock this out by interacting only with dictionaries, then let's complete this task using DataFrames.

Now let's repeat using DataFrames:

Nice! Always good to see that the results match, with 5626 dictionaries in our list vs. 5626 rows in our DataFrame.

From here, depending on your preference, you can move ahead with your plotting tasks (I would probably melt the polars DataFrame and plot a line for each expiration, but that's me).