Calculated Metrics API
Crack spreads, basis differentials, refinery margins, curve structure, physical premiums, fuel switching indicators, storage analytics, market annotations, and CFTC positioning data. All computed from real-time price data.
Quick Start
# Get 3-2-1 crack spread
curl -H "Authorization: Token YOUR_API_KEY" \ "https://api.oilpriceapi.com/v1/spreads/crack?type=3-2-1"
# Python
import requests
resp = requests.get(
"https://api.oilpriceapi.com/v1/spreads/crack",
headers={"Authorization": "Token YOUR_API_KEY"},
params={"type": "3-2-1"}
)
result = resp.json()["data"]
print("3-2-1 Crack: $" + str(result["value"]) + "/bbl")Spreads & Margins
/v1/spreads/crackCrack Spreads
Refinery crack spreads: 3-2-1 composite, jet fuel, diesel, gasoline. Measures the margin between crude oil input and refined product output.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| type | string | No | Spread type: 3-2-1, jet, diesel, gasoline (default: 3-2-1) |
| crude | string | No | Crude benchmark code (default: BRENT_CRUDE_USD) |
| start_date | string | No | For /historical: YYYY-MM-DD format |
| end_date | string | No | For /historical: YYYY-MM-DD format |
/v1/spreads/crack/historical, /v1/spreads/crack/all/v1/spreads/basisBasis Spreads
Hub-to-hub price differentials. Signals pipeline bottlenecks, regional supply/demand, and arbitrage windows.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| pair | string | Yes | Pair: WAHA_HH, BRENT_WTI, BRENT_DUBAI, TTF_HH, BRENT_OMAN |
| start_date | string | No | For /historical: YYYY-MM-DD format |
| end_date | string | No | For /historical: YYYY-MM-DD format |
/v1/spreads/basis/historical, /v1/spreads/basis/all/v1/spreads/marginRefinery Margin Indices
Composite yield-weighted refinery margins for three global regions.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| index | string | No | Index: usgc, singapore, nwe (default: usgc) |
| start_date | string | No | For /historical: YYYY-MM-DD format |
| end_date | string | No | For /historical: YYYY-MM-DD format |
/v1/spreads/margin/historical, /v1/spreads/margin/all/v1/spreads/curve-structureCurve Structure Analysis
Futures curve structure: backwardation/contango detection, term slope, severity classification, and human-readable signal.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| commodity | string | Yes | ICE_BRENT, ICE_WTI, ICE_GASOIL, NYMEX_NG, ICE_TTF |
| start_date | string | No | For /historical: YYYY-MM-DD format |
| end_date | string | No | For /historical: YYYY-MM-DD format |
/v1/spreads/curve-structure/allIntelligence Indicators
/v1/indicators/fuel-switchingFuel Switching / Oil-Parity
Calculates the oil-parity ratio (17.2% rule). When gas exceeds 17.2% of crude on an energy-equivalent basis, utilities switch from gas to oil.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| gas | string | No | Gas benchmark (default: NATURAL_GAS_USD) |
| crude | string | No | Crude benchmark (default: BRENT_CRUDE_USD) |
| start_date | string | No | For /historical: YYYY-MM-DD format |
| end_date | string | No | For /historical: YYYY-MM-DD format |
/v1/indicators/fuel-switching/historical/v1/indicators/price-contextEnriched Price Context
Wraps any commodity price with change metrics, percentile rankings, 52-week range, anomaly detection, and optionally related cross-commodity spreads.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| code | string | Yes | Any commodity code (e.g., BRENT_CRUDE_USD) |
| spreads | string | No | Set to "related" to include cross-commodity spreads |
| start_date | string | No | For /historical: YYYY-MM-DD format |
| end_date | string | No | For /historical: YYYY-MM-DD format |
/v1/indicators/storage-analyticsStorage Analytics
Enhanced Cushing/SPR storage: utilization %, draw/build rates, days to depletion, 5-year seasonal comparison, anomaly flags.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| location | string | No | CUSHING or SPR (default: CUSHING) |
| start_date | string | No | For /historical: YYYY-MM-DD format |
| end_date | string | No | For /historical: YYYY-MM-DD format |
/v1/indicators/storage-analytics/all/v1/indicators/annotationsMarket Annotations
Automatic detection of market events: price anomalies (z-score), 52-week records, velocity surges, and consecutive streaks.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| code | string | Yes | Commodity code to annotate |
| start_date | string | No | For /historical: YYYY-MM-DD format |
| end_date | string | No | For /historical: YYYY-MM-DD format |
/v1/indicators/annotations/batch?codes=CODE1,CODE2/v1/indicators/cftc-positioningCFTC COT Positioning
Speculative vs commercial positioning from CFTC Commitments of Traders reports. Weekly data for WTI, Brent, Natural Gas, Heating Oil, Gasoline.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| commodity | string | No | WTI, BRENT, NATURAL_GAS, HEATING_OIL, GASOLINE (default: WTI) |
| start_date | string | No | For /historical: YYYY-MM-DD format |
| end_date | string | No | For /historical: YYYY-MM-DD format |
/v1/indicators/cftc-positioning/historical, /v1/indicators/cftc-positioning/allAuthentication & Access
All calculated metrics endpoints require authentication via API key header:
Authorization: Token YOUR_API_KEYThese endpoints are available on Starter plans and above. Free and Hobby plans receive a 403 error with an upgrade prompt.
Ready to get started?
Crack spreads, basis differentials, and market intelligence via REST API.