agricultural_trade
Get the ERS U.S. agricultural trade data update - each table pivoted to a wide layout with the year and period in the rows and the trade direction, commodity, or trade partner spread into columns.
Examples
from openbb import obb
obb.usda.agricultural_trade(provider='usda')
# Get the top export markets for corn, by volume.
obb.usda.agricultural_trade(table='top_export_markets', commodity='Corn', provider='usda')
# Get the monthly agricultural trade totals since 2020.
obb.usda.agricultural_trade(table='monthly', start_year=2020, provider='usda')
Parameters
- standard
- usda
table: str | None
Default: exports_ytd
Description
Table to retrieve, pivoted to a wide layout. The natural 'many' dimension spreads into columns (trade direction for the summary and monthly tables, commodity for the year-to-date export and import tables, trade partner for the top-market tables) while a single pinned period column labels the rows. Valid tables are:
summary, monthly, exports_ytd, imports_ytd, top_export_markets, top_import_sources
period_basis: str | None
Reporting basis to keep, one of those the selected table publishes: 'Fiscal year', 'Calendar year', 'Fiscal year-to-date', 'Calendar year-to-date', or 'Monthly'. Filtering to one basis yields a single aligned time series instead of mixing annual totals, year-to-date spans, and single months. If None, the table's default basis is used.
value_type: str | None
Measure to spread into the wide cells, scoped to the table: 'value' (customs value), 'volume', or 'cif' (cost, insurance, and freight). If None or invalid for the table, the table's first measure is used.
commodity: str | None
Commodity whose trade partners spread into columns, for the top-export-market and top-import-source tables only, as a single exact name as published, e.g. 'Soybeans'. If None, the table's first commodity is used. Ignored by the summary, monthly, and year-to-date tables.
start_year: int | None
Start year for filtering the data. None returns from the beginning of the series.
end_year: int | None
End year for filtering the data. If None, returns up to the most recent year.
latest: bool | None
Default: False
Return only the most recent monthly update vintage for tables that retain the marketing year's prior vintages. No effect on the summary and monthly tables.
Returns
results: UsAgriculturalTrade
Serializable results.
provider: str | None
Provider name.
warnings: Optional[list[Warning_]]
List of warnings.
chart: Optional[Chart]
Chart object.
extra: dict[str, Any]
Extra info.
Data
- standard
- usda
period: str
Row label of the observation: the year with the published time span appended, e.g. '2026 May', '2026 October-May', or '2024 Fiscal year, October-September'.