API Reference

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.

Starter plan+REST APIJSON responsesHistorical time series

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

GET/v1/spreads/crack

Crack 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

Also available: /v1/spreads/crack/historical, /v1/spreads/crack/all

GET/v1/spreads/basis

Basis 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

Also available: /v1/spreads/basis/historical, /v1/spreads/basis/all

GET/v1/spreads/margin

Refinery 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

Also available: /v1/spreads/margin/historical, /v1/spreads/margin/all

GET/v1/spreads/physical-premium

Physical vs Futures Premium

Spot price premium over front-month futures — the "molecule contagion" signal of physical scarcity.

Parameters

Name	Type	Required	Description
commodity	string	No	Commodity: BRENT, WTI (default: BRENT)
start_date	string	No	For /historical: YYYY-MM-DD format
end_date	string	No	For /historical: YYYY-MM-DD format

Also available: /v1/spreads/physical-premium/historical, /v1/spreads/physical-premium/all

GET/v1/spreads/curve-structure

Curve 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

Also available: /v1/spreads/curve-structure/all

Intelligence Indicators

GET/v1/indicators/fuel-switching

Fuel 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

Also available: /v1/indicators/fuel-switching/historical

GET/v1/indicators/price-context

Enriched 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

GET/v1/indicators/storage-analytics

Storage 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

Also available: /v1/indicators/storage-analytics/all

GET/v1/indicators/annotations

Market 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

Also available: /v1/indicators/annotations/batch?codes=CODE1,CODE2

GET/v1/indicators/cftc-positioning

CFTC 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

Also available: /v1/indicators/cftc-positioning/historical, /v1/indicators/cftc-positioning/all

Authentication & Access

All calculated metrics endpoints require authentication via API key header:

Authorization: Token YOUR_API_KEY

These endpoints are available on Starter plans and above. Free plans receive a 403 error with an upgrade prompt.

Ready to get started?

Crack spreads, basis differentials, and market intelligence via REST API.

Get API Key View Pricing

Learn More

What Are Crack Spreads?Understanding Basis Spreads Backwardation vs Contango Oil-Parity & Fuel Switching Refinery Margins Explained Physical vs Futures Premium