Skip to main content

​
Purpose

Stocks-to-use is the standard buffer measure for a cereal balance: how much of a marketing year’s consumption is already sitting in store. A falling ratio is the earliest widely-published signal that a commodity’s slack is gone. Served from GET /api/resilience/v1/get-food-stocks?countryCode=<ISO2|WORLD> and MCP get_food_stocks. Both require a Pro subscription.

​
Source

USDA Production, Supply and Distribution (PSD) is the source for balances and stocks. Public domain, monthly release cycle, global coverage by commodity and country. FAOSTAT is applied after PSD as a production-only gap fill for commodity-country pairs the balance sheet missed. Those rows expose source: "faostat"; every stocks field on them is a placeholder, not a USDA/PSD measurement, and they do not carry a stocks-to-use ratio.

​
Commodities

wheat, corn, rice, soybeans, barley, palmOil. Pass commodity to narrow; omit it for every commodity the country reports. countryCode=WORLD returns the global balance, which is the aggregate PSD publishes — not a sum computed here over the country rows.

​
The ratio

Each row serves endingStocksTmt, productionTmt, totalUseTmt and the derived stocksToUse together, so a caller can see which side of the ratio moved. A ratio that fell because use rose is a different situation from one that fell because production failed, and the ratio alone cannot distinguish them.

​
Marketing years are not calendar years

This is the trap that matters, and it is why every row states its own marketingYear. A marketing year runs from harvest, so it differs by both commodity and country. Brazilian soybeans and US corn labelled “2025/26” cover different months. Northern and southern hemisphere wheat labelled the same year barely overlap. Consequences:
  • Never compare two countries’ figures because their year labels match. The label is not a period.
  • Never build a global total by summing country rows. Use countryCode=WORLD.
  • A country’s year can advance while its neighbour’s has not. That is the calendar, not a stale row.

​
Availability

Rows use explicit presence flags rather than numeric fields alone. hasEndingStocks and hasStocksToUse say whether endingStocksTmt and stocksToUse are measured values. FAOSTAT production-only fill rows can carry placeholder zeroes for endingStocksTmt, totalUseTmt, and stocksToUse while those stock flags are false. A commodity a country does not report is absent from the response. Zero stocks and no coverage are opposite readings, and callers must not infer one from the other.

​
Cadence

Monthly, following the PSD release. The seeder writes resilience:food-stocks:v1 and the accompanying seed-meta:resilience:food-stocks freshness key.