Physical supply and demand
The physical fundamentals of commodities (inventories, production, use and trade, and whole supply and demand balance
sheets) are served as reference series of kind physical, and economic for a price line. Each value is in the
series values shape; the registry, projections and publication lag are on economic and market series.
Routes
| you need | route |
|---|---|
| the physical concepts | GET /v1/series?kind=physical |
| one series, its observations, or projections | GET /v1/series/{key}, /observations, /projections |
| a futures family's supply and demand | GET /v1/markets/commodity/{root}/supply-demand |
Every parameter and response schema is in the API reference.
US petroleum
The weekly US petroleum balance:
| key | what it is |
|---|---|
series:us.crude_oil.stocks.commercial.nsa | commercial crude stocks, excluding the Strategic Petroleum Reserve |
series:us.crude_oil.stocks.cushing.nsa | crude stocks at Cushing |
series:us.crude_oil.stocks.strategic_reserve.nsa | the Strategic Petroleum Reserve itself |
series:us.gasoline.stocks.total.nsa | total gasoline stocks |
series:us.distillate_fuel_oil.stocks.total.nsa | total distillate stocks |
series:us.crude_oil.production.field.nsa | field production of crude oil |
series:us.refinery.utilization_rate.nsa | refinery utilization |
GET /v1/series?kind=physical lists the rest.
Periods
| figure | period.kind | what one value is |
|---|---|---|
| an inventory | calendar_day | the level at the end of the week, on the week-ending Friday |
| a production, input, or export figure | week | a daily average over the week, Saturday to Friday |
Units and status
The units are as published (Thousand Barrels, Thousand Barrels per Day, Percent). The series are not adjusted
(seasonal_adjustment: nsa).
Each value has status_not_stated and carries no source timestamp.
Release, revisions, and point in time
A week's values are normally published on Wednesday at 10:30 ET, sometimes later; refreshed_at says when they were
last confirmed, and observed_through names the newest week held. The newest 13 weeks can still change; an older week does not change here. A
known_at answer serves the values as they were recorded at the time
(point in time).
Withdrawn and unlisted weeks
A week that a later publication lists with no value is withdrawn: it appears in missing as status_withdrawn, and
a known_at before the withdrawal answers the number held then.
A value the latest publication no longer carries is served marked
(values missing from the latest publication),
on current reads only, never on a known_at answer.
US grains and oilseeds (WASDE)
The US balance sheets of the WASDE (World Agricultural Supply and Demand Estimates) report are served for corn, soybeans, wheat (all classes), soybean oil, and soybean meal. Every line of each table is a series:
- area planted and harvested, yield, beginning stocks, production, imports, total supply, each use, exports, total use,
and ending stocks (
physical); - the season-average price (
economic).
Examples are series:us.corn.stocks.ending, series:us.soybeans.use.crush, and series:us.wheat.price.farm_avg.
Marketing years
A period is a marketing year (period.kind: marketing_year, labeled like 2026/27;
periods), with its start and end:
| commodity | marketing year begins |
|---|---|
| corn, soybeans | September 1 |
| wheat | June 1 |
| soybean oil, soybean meal | October 1 |
Release and revisions
WASDE is published monthly, between the 8th and the 12th at 12:00 ET; refreshed_at says when the report was last
confirmed. A revised number keeps the earlier one, and known_at answers what the report said then. A settled
marketing year before the live report has only its last report's values, known from when that report was recorded; no earlier vintage is served.
freshness.observed_through is the newest observed marketing year's end, not WASDE's release lag.
Estimates and projections
Each value states what kind of number it is in value_kind:
| WASDE column or line | value_kind |
|---|---|
Proj. | projection |
Est. | estimate |
| a settled year | the line's kind: observed, or derived for a total or a residual |
The projected year is served by /projections, never as latest
(served periods). For example, while corn's
2026/27 year is projected, its latest is the 2025/26 estimate:
curl "https://api.tauric.ai/v1/series/us.corn.stocks.ending" \
-H "Authorization: Bearer $TAURIC_API_KEY"
curl "https://api.tauric.ai/v1/series/us.corn.stocks.ending/projections" \
-H "Authorization: Bearer $TAURIC_API_KEY"
curl "https://api.tauric.ai/v1/markets/commodity/ZC/supply-demand" \
-H "Authorization: Bearer $TAURIC_API_KEY"
A futures family's supply and demand
GET /v1/markets/commodity/{root}/supply-demand is the physical supply and demand of the commodity a futures family
delivers. root is the family, such as CL or XNYM:CL (futures).
| family | members |
|---|---|
CL | the US crude balance: commercial, SPR, Cushing, and total crude-and-product stocks, field production, refinery net input, crude exports, refinery utilization |
RB | US gasoline stocks and refinery utilization |
HO | US distillate stocks and refinery utilization |
ZC, ZS, ZW, ZL, ZM | the WASDE US balance sheets of corn, soybeans, wheat, soybean oil, and soybean meal |
Each member is its /v1/series/{key} answer, with two differences: classification is null (the view's family and
dataset classify it), and it adds projections, exactly its /v1/series/{key}/projections list. That list holds the
projected marketing year for WASDE members and is empty for the weekly petroleum members.
A member with no value available is named in missing
(missing members); when no member has one, the answer is
503 temporarily_unavailable.
Any other family is 404 not_supported.