Models

oilpriceapi.models

OilPriceAPI Data Models

Pydantic models for API responses.

Price

Bases: BaseModel

Single price data point.

is_up property

Check if price is up.

is_down property

Check if price is down.

parse_timestamp(v) classmethod

Parse timestamp from various formats.

__str__()

String representation.

PriceResponse

Bases: BaseModel

Response from current price endpoint.

MultiplePricesResponse

Bases: BaseModel

Response with multiple prices.

HistoricalPrice

Bases: BaseModel

Historical price data point.

parse_date(v) classmethod

Parse date from various formats.

HistoricalResponse

Bases: BaseModel

Response from historical data endpoint.

PaginationMeta

Bases: BaseModel

Pagination metadata.

Commodity

Bases: BaseModel

Commodity information.

CommodityListResponse

Bases: BaseModel

Response with available commodities.

ApiStatus

Bases: BaseModel

API status information.

UsageStats

Bases: BaseModel

API usage statistics.

DieselPrice

Bases: BaseModel

State average diesel price data.

parse_updated_at(v) classmethod

Parse updated_at from various formats.

DieselStationLocation

Bases: BaseModel

Geographic coordinates for a diesel station.

DieselStation

Bases: BaseModel

Diesel station with pricing information.

parse_last_updated(v) classmethod

Parse last_updated from various formats.

DieselRegionalAverage

Bases: BaseModel

Regional average diesel price for comparison.

DieselSearchArea

Bases: BaseModel

Search area details for station query.

DieselStationsMetadata

Bases: BaseModel

Metadata about diesel stations query.

parse_timestamp(v) classmethod

Parse timestamp from various formats.

DieselStationsResponse

Bases: BaseModel

Response from diesel stations endpoint.

PriceAlert

Bases: BaseModel

Price alert configuration and status.

parse_datetime(v) classmethod

Parse datetime from various formats.

WebhookTestResponse

Bases: BaseModel

Response from webhook test endpoint.

MarketBriefForecast

Bases: BaseModel

1-month forecast block attached to a market-brief commodity.

MarketBriefCommodity

Bases: BaseModel

A single commodity entry within a market brief.

MarketBrief

Bases: BaseModel

Multi-commodity structured (+ optional narrative) market summary.

Returned by client.market_brief(...) / await client.market_brief(...).

parse_as_of(v) classmethod

Parse as_of timestamp from various formats.

Subscription

Bases: BaseModel

An agent subscription ("watch") that periodically evaluates commodities.

parse_datetimes(v) classmethod

Parse datetime fields from various formats.

SubscriptionEventSnapshot

Bases: BaseModel

One watched code's price at the moment a subscription event was recorded.

Built by the API's MarketBriefBuilder#snapshot_hash.

SubscriptionEventDelta

Bases: BaseModel

One code's change since the previous event of the same subscription.

Built by the API's Watch#compute_deltas.

SubscriptionEvent

Bases: BaseModel

A single event emitted by a subscription, returned from the poll endpoint.

Typed from GET /v1/subscriptions/events as the API sends it (#149). snapshot and deltas are keyed by commodity code. deltas is {} on a subscription's first event, and a code is absent from it when either snapshot lacked a price.

created_at property

Deprecated alias for observed_at; removed in 2.0.0.

The API never sent created_at on an event, so this always read None. The event's timestamp is observed_at.

type property

Deprecated; always None, removed in 2.0.0.

The events API has no event type: every event is an interval snapshot.

code property

Deprecated; always None, removed in 2.0.0.

An event can cover several codes: use snapshot.keys().

payload property

Deprecated; always None, removed in 2.0.0.

The event data is in snapshot and deltas.

DataConnectorPrice

Bases: BaseModel

Price from connected data source (BYOS - Bring Your Own Subscription).

parse_timestamp(v) classmethod

Parse timestamp from various formats.

__str__()

String representation.

FuelSurchargeDieselBand

Bases: BaseModel

The DOE diesel price band a carrier's published table matched.

Either bound may be null: an open-ended top band has no max.

FuelSurchargeRate

Bases: BaseModel

One carrier fuel-surcharge rate (LTL, or one parcel service level).

Every key the API always sends is required here. A key the API sends as null stays None; a key missing from the payload is a malformed response, never a default. service_level is only sent for parcel rates.

parse_effective_date(v) classmethod

Accept only the API's YYYY-MM-DD string (or a date).

parse_retrieved_at(v) classmethod

Parse an ISO-8601 timestamp and require an explicit UTC offset.

FuelSurchargeHistoryMeta

Bases: BaseModel

Pagination metadata exactly as the history routes send it.

FuelSurchargeHistoryPage

Bases: BaseModel

One page of weekly fuel-surcharge history, newest first.

ParcelFuelSurchargeCarrier

Bases: BaseModel

A parcel carrier with its latest rate for each service level.

Spreads and Indicators

oilpriceapi.metrics_models

Typed models for the calculated-metrics routes: /v1/spreads/* and /v1/indicators/* (#99).

Every model is typed from the production wire shape (captured 2026-09-13) and from the serializers in app/services/calculated_metrics/ on the API.

Conventions, applied throughout:

• A key the server always emits is required. If the server can emit it as null it is Optional[...] without a default, so a body that drops the key fails validation instead of being silently read as None.
• A key the server only emits conditionally (for example data_stale, the change_* deltas, or the inner fields of a block that is {} when there is too little history) is Optional[...] = None. None there means "the server did not send it", never "false" or "zero".
• Values are kept exactly as sent: no rounding, unit conversion or clamping. Timestamps parse to timezone-aware datetime; calendar dates to date.
• Unknown keys are preserved (extra="allow") so a field the API adds later is not dropped on the floor.

MetricChanges

Bases: _WireModel

1-day / 1-week / 1-month deltas.

The server only emits a pair when a prior value exists for that horizon, so every field is optional and an absent horizon stays None.

HistoryPeriod

Bases: _WireModel

The window the server applied (it echoes defaults and its 2-year cap).

HistoryCoverage

Bases: _WireModel

What a history response actually contains, as opposed to what was asked.

PricedLeg

Bases: _WireModel

One priced input to a spread, e.g. {"code", "price", "unit"}.

CrackSpread

Bases: _WireModel

GET /v1/spreads/crack and each entry of /crack/all.

components is keyed crude + product for single-product cracks and crude + gasoline + diesel for the 3-2-1 composite.

CrackSpreadAll

Bases: _WireModel

GET /v1/spreads/crack/all.

CrackSpreadPoint

Bases: _WireModel

One day of crack history. The 3-2-1 composite carries gasoline and diesel; single-product cracks carry product.

CrackSpreadHistory

Bases: _WireModel

GET /v1/spreads/crack/historical.

GasoilCrackLeg

Bases: _WireModel

A futures leg of the European gasoil crack, with its contract month.

GasoilCrackConversion

Bases: _WireModel

The tonne-to-barrel conversion the server applied.

GasoilCrackSpread

Bases: _WireModel

GET /v1/spreads/gasoil-crack (ICE Low Sulphur Gasoil vs ICE Brent).

BasisSpread

Bases: _WireModel

GET /v1/spreads/basis and each entry of /basis/all.

components maps each leg's commodity code to its price. negative_streak_days is only sent for pairs that track it (WAHA_HH).

BasisSpreadPoint

Bases: _WireModel

One day of basis history: value = code_a - code_b.

BasisSpreadHistory

Bases: _WireModel

GET /v1/spreads/basis/historical.

CurveStructureSpreads

Bases: _WireModel

Front-month minus later-month spreads. The server omits a horizon it could not compute, so m1_m3 and m1_m12 may be absent.

CurveStructure

Bases: _WireModel

GET /v1/spreads/curve-structure and each entry of /all.

RefineryMargin

Bases: _WireModel

GET /v1/spreads/margin and each entry of /margin/all.

product_basket only contains products the server had a price for.

RefineryMarginHistory

Bases: _WireModel

GET /v1/spreads/margin/historical.

PhysicalPremium

Bases: _WireModel

GET /v1/spreads/physical-premium and each entry of /all.

PhysicalPremiumHistory

Bases: _WireModel

GET /v1/spreads/physical-premium/historical.

FuelSwitchingContext

Bases: _WireModel

Trailing-year context. The server sends {} with fewer than 10 observations, so every field is optional.

FuelSwitching

Bases: _WireModel

GET /v1/indicators/fuel-switching.

FuelSwitchingHistory

Bases: _WireModel

GET /v1/indicators/fuel-switching/historical.

PriceContextDetail

Bases: _WireModel

Where the latest price sits. Every metric other than anomaly is only sent when the server had enough history to compute it.

RelatedSpread

Bases: _WireModel

A spread related to the requested code (spreads=related).

value is numeric for basis/crack/parity entries and a structure label (e.g. "backwardation") for the curve-structure entry, which carries slope and no unit.

PriceContext

Bases: _WireModel

GET /v1/indicators/price-context.

StorageDrawRate

Bases: _WireModel

{} when the latest report has no weekly change.

StorageSeasonal

Bases: _WireModel

{} with fewer than three same-week observations in five years.

StorageRange

Bases: _WireModel

{} when there is no data in the trailing 52 weeks.

StorageAnalytics

Bases: _WireModel

GET /v1/indicators/storage-analytics and each entry of /all.

MarketAnnotation

Bases: _WireModel

One notable condition. Extra fields depend on type: anomaly (z_score, mean_90d), velocity (pct_change_5d, z_score), streak (direction, streak_days), record (record_type).

MarketAnnotations

Bases: _WireModel

GET /v1/indicators/annotations.

MarketAnnotationsBatch

Bases: _WireModel

GET /v1/indicators/annotations/batch.

annotated omits codes the server has no data for and codes with no annotations, so it can be shorter than total_codes.

CftcPositioning

Bases: _WireModel

GET /v1/indicators/cftc-positioning and each entry of /all.

CftcPositioningHistory

Bases: _WireModel

GET /v1/indicators/cftc-positioning/historical.