> ## Documentation Index
> Fetch the complete documentation index at: https://www.worldmonitor.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Food Stocks & Stocks-to-Use

> How WorldMonitor serves USDA PSD cereal ending stocks, production, use, and the stocks-to-use ratio per commodity and country, and why marketing years are not comparable across countries.

## 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

```text theme={null}
stocks-to-use = ending stocks / total use
```

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.

## Related

* [Pro Intelligence Suite](/docs/pro-intelligence-suite)
* [Five-factor scorecard](/docs/methodology/five-factor-scorecard) — consumes stocks-to-use as its food pillar
* [Data sources](/docs/data-sources)