usda_psd_get_time_series
Retrieve USDA PSD time-series data for a commodity and country across market years, optionally limited to selected attributes, returning upstream records without gap filling.
Instructions
One country's PSD figures for a commodity over a range of market years.
One request to PSDData_GetCountryCommodityDataByYear per market year, oldest
first, at the client's pace of one request per second, and each counts against
api.data.gov's quota of 1,000 requests per hour per key: 2021 to 2023 is three
requests and about three seconds, 1960 to 2026 sixty-seven, so ask for the years you
need; a range of more than 100 market years is refused. Of each answer the records
of the attributes asked for, or all of them when attribute_id is omitted, are
kept exactly as upstream sent them, ordered by market year and within a year in
upstream's order: value is in its unit_id, and calendar_year and
month name the release that last revised that year, which may differ from year
to year. A market year PSD has no data for (its empty HTTP 404, recorded for 1900),
or whose answer has no record for the attributes, is absent from the list: no gap is
filled, nothing interpolated, no error raised; a range without any record is an
empty list. A year beyond PSD's forecasts is expected to answer the same 404 (not
recorded) and still costs its request. Any other error, the gateway's own 404
included, is raised. meta.vintage is the latest release across the records
("2026-07"); meta.published_at stays empty. Codes, every attribute id, both
years and the range are checked before the first request.
Args:
commodity_code: PSD commodity code, seven digits, e.g. "0410000" (Wheat),
"0440000" (Corn), "2222000" (Oilseed, Soybean).
country_code: PSD country code (not ISO), e.g. "US" (United States), "BR"
(Brazil), "E4" (European Union).
start_year: First PSD market year, 1960 or later (PSD: "PSD Database has data
for most commodities since year 1960"), e.g. 2021.
end_year: Last PSD market year, included, e.g. 2023; not before
start_year and at most 99 years after it. No other bound.
attribute_id: PSD attribute id, or a list of them, e.g. 28 (Production),
[28, 88] (Production and Exports), 176 (Ending Stocks);
list_commodity_attributes lists them. Omit it (None) for every
attribute of each answer, 15 a year for wheat in the United States. An empty
list is refused.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"commodity_code": "<commodity_code>",
"country_code": "<country_code>",
"start_year": "<start_year>",
"end_year": "<end_year>"
},
"name": "usda_psd_get_time_series"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| end_year | Yes | ||
| start_year | Yes | ||
| attribute_id | No | ||
| country_code | Yes | ||
| commodity_code | Yes |