# Commodity Seasonality API > The calendar patterns commodity traders position around, computed live from ~10 years of Yahoo Finance monthly futures data (no key, nothing stored). Commodities are the most seasonal market there is: natural gas tends to rally into winter heating demand, gasoline into the summer driving season, grains around the planting and harvest calendar. This measures it directly — for each commodity it takes a decade of monthly returns, groups them by calendar month, and returns the average return in each of the twelve months, the share of years that month was positive (the win rate), and the historically strongest and weakest months. The seasonality endpoint returns one commodity's full 12-month seasonal profile plus the current month's historical bias. The month endpoint flips it around: for a given calendar month it ranks every commodity by its historical average return, so you can see what is seasonally bullish or bearish right now. The commodities endpoint lists what is covered. The commodity-seasonality / calendar-pattern cut — distinct from the FX-seasonality API (currencies), the commodity-price feed, the commodity-spreads and the commodity-momentum APIs. It answers what a commodity usually does this month, not what it costs today. ## Authentication All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys. ```bash curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/commodityseasonality-api/..." ``` ## Pricing - **Free** (Free) — 820 calls/Mo, 2 req/s - **Starter** ($10/Mo) — 18,800 calls/Mo, 6 req/s - **Pro** ($32/Mo) — 92,500 calls/Mo, 16 req/s - **Business** ($76/Mo) — 505,000 calls/Mo, 40 req/s ## Endpoints ### Seasonality #### `GET /v1/seasonality` — One commodity 12-month seasonal profile with best/worst month and current bias **Parameters:** - `commodity` (query, required, string) — Key, name or alias (see /v1/commodities) Example: `natural_gas` **Example:** ```bash curl -H "x-oanor-key: $KEY" \ "https://api.oanor.com/commodityseasonality-api/v1/seasonality?commodity=natural_gas" ``` **Response:** ```json { "data": { "name": "Natural Gas", "note": "Average month-over-month return in each calendar month over ~10 years, with win_rate_pct (share of years that month was positive) and the sample size (years). Seasonal tendencies are statistical, not guarantees. Not financial advice.", "group": "energy", "months": [ { "month": "January", "years": 8, "month_num": 1, "win_rate_pct": 50, "avg_return_pct": 0.21 }, { "month": "February", "years": 9, "month_num": 2, "win_rate_pct": 22, "avg_return_pct": -7.86 }, { "month": "March", "years": 8, "month_num": 3, "win_rate_pct": 50, "avg_return_pct": 2.16 }, { "month": "April", "years": 9, "month_num": 4, "win_rate_pct": 67, "avg_return_pct": 2.44 }, { "month": "May", "years": 9, "month_num": 5, "win_rate_pct": 56, "avg_return_pct": 4.48 }, { "month": "June", "years": 10, "month_num": 6, "win_rate_pct": 30, …(truncated, see openapi.json for full schema) ``` ### Month #### `GET /v1/month` — Every commodity ranked by historical average return in a calendar month **Parameters:** - `month` (query, optional, string) — 1-12 or month name (default current) Example: `December` **Example:** ```bash curl -H "x-oanor-key: $KEY" \ "https://api.oanor.com/commodityseasonality-api/v1/month?month=December" ``` **Response:** ```json { "data": { "note": "Every commodity ranked by its historical average return in December over ~10 years, most seasonally bullish first. Use bullish/bearish for the headline seasonal trades this month.", "month": "December", "source": "Yahoo Finance", "bearish": [ { "name": "Natural Gas", "win_rate_pct": 13, "avg_return_pct": -17.48 }, { "name": "Sugar", "win_rate_pct": 50, "avg_return_pct": -2.26 }, { "name": "Soybean Oil", "win_rate_pct": 25, "avg_return_pct": -1.14 }, { "name": "Coffee", "win_rate_pct": 13, "avg_return_pct": -1 }, { "name": "Cotton", "win_rate_pct": 60, "avg_return_pct": 0.89 } ], "bullish": [ { "name": "Lean Hogs", "win_rate_pct": 88, "avg_return_pct": 9.39 }, { "name": "Platinum", "win_rate_pct": 63, "avg_return_pct": 7.48 }, { "name": "Silver", "win_rate_pct": 75, "avg_return_pct": 6.75 }, { "name": "Brent Crud …(truncated, see openapi.json for full schema) ``` ### Commodities #### `GET /v1/commodities` — Supported commodities and groups **Example:** ```bash curl -H "x-oanor-key: $KEY" \ "https://api.oanor.com/commodityseasonality-api/v1/commodities" ``` **Response:** ```json { "data": { "note": "Supported commodities. Pass key/name/alias as commodity= to /v1/seasonality, or month= (1-12 or name) to /v1/month.", "count": 20, "groups": [ "energy", "metals", "grains", "softs", "livestock" ], "source": "Yahoo Finance", "commodities": [ { "key": "crude_oil", "name": "WTI Crude Oil", "group": "energy", "symbol": "CL=F" }, { "key": "brent", "name": "Brent Crude Oil", "group": "energy", "symbol": "BZ=F" }, { "key": "natural_gas", "name": "Natural Gas", "group": "energy", "symbol": "NG=F" }, { "key": "gasoline", "name": "RBOB Gasoline", "group": "energy", "symbol": "RB=F" }, { "key": "heating_oil", "name": "Heating Oil", "group": "energy", "symbol": "HO=F" }, { "key": "gold", "name": "Gold", "group": "metals", "symbol": "GC=F" }, { "key": "silver", "name": "Silver", "g …(truncated, see openapi.json for full schema) ``` ### Meta #### `GET /v1/meta` — Service metadata **Example:** ```bash curl -H "x-oanor-key: $KEY" \ "https://api.oanor.com/commodityseasonality-api/v1/meta" ``` **Response:** ```json { "data": { "note": "commodity is a key/name/alias (natural_gas, gasoline, GC=F; see /v1/commodities). month is 1-12 or a name (default current month). Averages use ~10 years of monthly returns grouped by calendar month. Read fresh per call, nothing cached.", "groups": [ "energy", "metals", "grains", "softs", "livestock" ], "source": "Yahoo Finance monthly commodity futures, ~10y range, live", "service": "commodityseasonality-api", "endpoints": { "GET /v1/meta": "This document.", "GET /v1/month": "Every commodity ranked by historical average return in a calendar month (month=December).", "GET /v1/commodities": "The supported commodities and groups.", "GET /v1/seasonality": "One commodity's 12-month seasonal profile with best/worst month and current-month bias (commodity=natural_gas)." }, "description": "Commodity seasonality — the calendar patterns commodity traders position around, from ~10 years of Yahoo Finance monthly futures data (no key, nothing stored). seasonality returns one commodity's 12-month seasonal profile (average return and win rate per calendar month, best/worst month, current-month bias). month ranks every commodity by its historical average return in a given calendar month. commodities lists what is covered. The commodity-seasonality / calendar-pattern cut — distinct from the FX- …(truncated, see openapi.json for full schema) ``` --- Marketplace page: https://www.oanor.com/api/commodityseasonality-api OpenAPI spec: https://www.oanor.com/api/commodityseasonality-api/openapi.json