Commodity 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?instrument_type=physical |
| one series, its observations, or projections | GET /v1/series/{key}, /observations, /projections |
| a futures family's supply and demand | GET /v1/futures/{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?instrument_type=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's status is null, and it carries no timestamp of its own.
Release, revisions, and point in time
A week's values are usually published on Wednesday at 10:30 New York time, sometimes later; refreshed_at says when they were
last confirmed, and through names the newest week held. The newest 13 weeks can still change; an older week does not change. 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, and a known_at before the withdrawal answers the number held then.
A value the latest publication no longer carries is still served as last published (values missing from the latest publication).
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 on a day from the 8th to the 12th of the month, usually at 12:00 New York time; 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 known_at at or
after a report's publication reads that report.
freshness.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/futures/ZC/supply-demand" \
-H "Authorization: Bearer $TAURIC_API_KEY"
A futures family's supply and demand
GET /v1/futures/{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 population.missing
(missing members); when no member has one, the answer is
503 temporarily_unavailable.
Any other family is 404 not_supported.