Magpie — USDA Ag Markets: Grain, Fertilizer, WASDE & Export Sales

Derived comparison of ESR contracted export sales against GATS actual shipments for one commodity: total contracted, total shipped, and the gap in metric tons — a positive gap means sold but not yet shipped. Use to gauge the unshipped export backlog; use get_export_sales or get_trade_flows instead for the underlying weekly or monthly detail. Read-only; no API key. This is a computed aggregate across both stored datasets over all stored periods, not a USDA-published figure; totals are rounded to whole tons.

Most recent weekly NASS crop condition ratings for corn, soybeans, or wheat — the share of the crop rated excellent, good, fair, poor, and very poor, plus a combined good+excellent percentage — from USDA NASS QuickStats. Use for current crop health; use get_crop_condition_history instead for week-by-week change across the season, and get_crop_progress for growth-stage pace. Read-only lookup of stored statistics; no API key. Ratings are published weekly in season, but the stored copy refreshes weekly, so the returned `period` (e.g. 2026-W30) is the freshest stored week, not necessarily the current one.

Week-by-week NASS crop condition ratings for corn, soybeans, or wheat across the growing season — each week's excellent/good/fair/poor/very poor shares plus a combined good+excellent percentage — from USDA NASS QuickStats. Use to track crop health trends or compare weeks within the season; use get_crop_condition instead when only the latest week matters. Read-only lookup of stored statistics; no API key. Returns up to `weeks` most recent stored weeks, oldest first (default 12, max 52); coverage is the current season, national plus major corn-belt states, and the stored copy refreshes weekly.

Most recent weekly NASS crop progress for corn, soybeans, or wheat — the share of the crop at each growth stage (planted, emerged, silking, harvested, and similar; the stages present vary by commodity) — from USDA NASS QuickStats. Use for current season pace; use get_crop_progress_history instead for week-by-week pace across the season, and get_crop_condition for health ratings. Read-only lookup of stored statistics; no API key. Progress is published weekly in season, but the stored copy refreshes weekly; the returned `period` (e.g. 2026-W30) is the freshest stored week.

Week-by-week NASS crop progress for corn, soybeans, or wheat across the growing season — each week's share of the crop at each growth stage (planted, emerged, silking, harvested, and similar) — from USDA NASS QuickStats. Use to track season pace or compare against earlier weeks; use get_crop_progress instead when only the latest week matters. Read-only lookup of stored statistics; no API key. Returns up to `weeks` most recent stored weeks, oldest first (default 12, max 52); the stages present vary by commodity and point in the season. Coverage is the current season, national plus major corn-belt states, and the stored copy refreshes weekly.

Annual NASS survey statistics — yield, production, planted or harvested area — for a commodity at national or state level, from USDA NASS QuickStats. These are survey estimates, not market prices. Use for production fundamentals; use get_crop_condition or get_crop_progress instead for in-season weekly crop status. Read-only lookup of stored statistics; no API key. Returns every stored period (year) for the requested statistic, most recent first; the stored copy refreshes weekly. Commodity, statistic, and geography are case-insensitive and default to CORN, YIELD, and US.

Weekly price history for one dairy product, from the same USDA MARS weekly dairy reports behind get_dairy_price. Use for trends across report weeks; use get_dairy_price instead when only the latest quote matters. Read-only lookup of stored reports; no API key. Returns up to `periods` most recent report rows, oldest first (default 30, max 365); geography defaults to US-Central and cheese reports use geography 'US'. Butter returns a withheld notice — USDA publishes only price differentials for butter, no US base price.

Latest price for one dairy product, from USDA MARS weekly dairy reports — the same series get_dairy_history extends over time. Use for a current quote; use get_dairy_history instead for the weekly trend. Read-only lookup of stored reports; no API key. Geography defaults to US-Central (cheese reports are national and use geography 'US'). Butter is deliberately withheld: USDA publishes only price differentials for butter, no US base price, so butter returns a withheld notice instead of a misleading value.

Latest week of USDA export sales for one commodity from the FAS Export Sales Reporting (ESR) system — sales contracted by exporters, not yet necessarily shipped. Use for current foreign demand; use get_export_sales_history instead for the weekly trend, and get_trade_flows for actual shipped volumes. Read-only lookup of stored reports; no API key. ESR reports weekly (released Thursdays); returns the most recent stored week's weekly exports, outstanding sales, net sales for the current marketing year, and total commitments per destination country, each row with its reported unit. Omit `country` to include all destinations.

Weekly export sales time series for one commodity, and optionally one destination country, from the same FAS ESR weekly reports behind get_export_sales. Use for demand trends across weeks; use get_export_sales instead when only the latest week matters, and compare_contracts_vs_shipments to set contracted sales against actual shipments. Read-only lookup of stored reports; no API key. Returns up to `weeks` most recent weeks, oldest first (default 12, max 52); without a `country`, each week covers all destinations combined as stored.

Price history for one fertilizer product across report periods, from the same twice-monthly USDA MARS production cost reports behind get_fertilizer_price. Use for input-cost trends; use get_fertilizer_price instead when only the latest quote matters. Read-only lookup of stored reports; no API key. Returns up to `periods` most recent reports, oldest first (default 12, max 52 — roughly two years of twice-monthly reports).

Latest price for one fertilizer product from USDA MARS production cost reports (Illinois-led regional coverage) — the same series get_fertilizer_history extends over time. Use for a current input-cost quote; use get_spreads instead to relate fertilizer cost to corn or cattle prices. Read-only lookup of stored reports; no API key. The reports publish twice a month and are fetched on the 1st and 15th, so the latest price can be up to about two weeks old; returns the price, its unit (typically USD per ton), and the change versus the prior report.

Daily cash price history for one grain commodity in one state, from the same USDA MARS daily reports behind get_grain_price. Use for trends or day-over-day comparison; use get_grain_price instead when only the latest quote matters. Read-only lookup of stored reports; no API key. Returns up to `periods` most recent daily report rows, oldest first; `periods` counts report rows, not calendar days (default 30, max 365).

Latest cash grain price for one commodity in one state, from USDA MARS daily market reports — the same series get_grain_history extends over time. Use for a current quote; use get_grain_history instead for trends across days. Read-only lookup of stored reports; no API key. Returns the most recent report's price with its unit (USD per bushel in most markets) and market location; a commodity/state pair with no report returns a no-data error rather than a stale price.

Price history for one livestock category in one region, from the same USDA MARS reports behind get_livestock_price (daily direct-trade reports plus weekly auction summaries). Use for trends; use get_livestock_price instead when only the latest quote matters. Read-only lookup of stored reports; no API key. Returns up to `periods` most recent report rows, oldest first; `periods` counts report rows, not calendar days (default 30, max 365).

Latest price for one livestock category in one region, from USDA MARS direct-trade and auction reports — the same series get_livestock_history extends over time. Use for a current quote; use get_livestock_history instead for trends. Read-only lookup of stored reports; no API key. Returns the most recent report's price and its unit (typically USD per cwt); direct-trade reports can skip weeks when no trades occur, and a category/region pair with no report returns a no-data error rather than a stale price.

Derived input-to-output price spreads computed from the latest stored Magpie prices: corn-to-nitrogen cost broken down per fertilizer product (bushels of corn per ton of product and per pound of actual N), the soybean-to-corn price ratio, and the feeder-to-fed cattle spread. Use for planting and feeding economics; use the raw price tools (get_grain_price, get_fertilizer_price, get_livestock_price) instead for the quotes behind a spread. Read-only; no API key. These are Magpie calculations over stored USDA MARS prices, not USDA-published figures; a spread is omitted when either side has no stored price. Geography defaults to IL and applies to both sides of each spread.

Monthly US agricultural export shipments by destination, from USDA GATS (Census trade data) — quantities and values actually shipped, not sales contracted. Use for realized trade volumes; use get_export_sales instead for contracted-but-unshipped demand, and compare_contracts_vs_shipments for the sold-versus-shipped gap. Read-only lookup of stored Census data; no API key. Coverage is a rolling 24 months, refreshed monthly; quantities are in metric tons with values in USD. Some commodities are withheld when GATS unit inconsistencies fail a dollars-per-ton sanity check — a withheld result says so explicitly instead of returning bad numbers.

Revision history of one WASDE projection figure (default ending_stocks) across monthly reports — how the estimate for a commodity and marketing year moved as successive WASDE reports landed. Use to study estimate revisions; use get_wasde_projection instead for the full current balance sheet. Read-only lookup of stored projections; no API key. Returns up to 24 monthly report values, oldest first, each with its report date and unit, for the requested commodity, attribute, and country (default WORLD).

Latest USDA WASDE supply/demand projections for one commodity — beginning stocks, production, imports, exports, domestic consumption, and ending stocks — from the FAS PSD database behind the monthly WASDE report. Use for the current balance-sheet outlook; use get_wasde_history instead to see how a single figure has been revised across reports. Read-only lookup of stored projections; no API key. Returns the newest stored report's values for the requested marketing year (default: the current marketing year, where e.g. 2026 means the 2025/26 season) and country (default WORLD aggregate; US, BR, and AR are also tracked).

Lists the dairy product slugs this API tracks (cheese, butter, dry_whey, fluid_milk) with display labels. Use to discover valid `product` values before calling get_dairy_price or get_dairy_history. Read-only; no API key. Butter is listed for completeness but its price is withheld in the price tools — USDA reports no US base price for butter.

Lists the commodities tracked in USDA export sales reporting (wheat, barley, corn, sorghum, soybeans, soybean meal, soybean oil, cotton, rice) with their FAS commodity codes. Use to discover valid `commodity` slugs before calling get_export_sales or get_export_sales_history. Read-only; no API key. Slugs map to FAS 'all' aggregate commodity codes where available.

Lists the fertilizer product slugs this API tracks (anhydrous ammonia, urea, DAP, MAP, potash, liquid N 28/32, ATS, farm diesel, biodiesel) with display labels. Use to discover valid `product` values before calling get_fertilizer_price or get_fertilizer_history. Read-only; no API key. The list is the configured catalog across the tracked MARS production cost reports, not a live availability check.

Lists the commodities tracked in GATS trade flows (matched to Census data by HS chapter) with display labels. Use to discover valid `commodity` slugs before calling get_trade_flows or compare_contracts_vs_shipments. Read-only; no API key. The list is the configured catalog — individual commodities can still be withheld in get_trade_flows when their source data fails sanity checks.

Lists the grain commodity slugs this API tracks (corn, soybeans, wheat, sorghum, oats, barley, rice) with display labels. Use to discover valid `product` values before calling get_grain_price or get_grain_history. Read-only; no API key. The list is the configured MARS catalog, not a live availability check — a listed product can still have no report for a given state.

Lists the livestock category slugs this API tracks (fed_cattle, feeder_cattle, cows, hogs, sheep) with display labels. Use to discover valid `product` values before calling get_livestock_price or get_livestock_history. Read-only; no API key. The list is the configured catalog, not a live availability check — some categories trade sporadically and can have no recent report in a region.

Lists the commodities tracked in WASDE projections (corn, wheat, soybeans, soybean meal, soybean oil, rice, barley, cotton) with their FAS PSD commodity codes. Use to discover valid `commodity` slugs before calling get_wasde_projection or get_wasde_history. Read-only; no API key.