usda_psd_get_top_countries
Rank the top n countries by a selected USDA PSD commodity attribute for a given market year, optionally limiting results to a region or excluding aggregate groupings.
Instructions
The n countries with the largest value of one PSD attribute for a commodity and year.
One request to PSDData_GetCommodityDataByYear (every country); its records with
attribute_id are sorted by value, largest first, and the first n kept,
each exactly as upstream sent it. Equal values keep upstream's order. Values are
compared as sent, with no unit check: each record carries its own unit_id, the
unit of its value (in the recorded answers, wheat and corn 2023, every country
reports an attribute in the same unit). By default nothing is excluded: PSD's country
list holds groupings that rank alongside countries, above all the European Union
("E4", second in wheat production for 2023), and residual aggregates such as
"T3" (Africa, NEC), "X8" (Southern Asia NEC) and "Z7" (Other Pacific
Islands, NEC); exclude_groupings=True leaves those out, and region_code keeps
the countries of one PSD region. The data records carry no region, so each record's
country is looked up in the packaged country list; a country it lacks has no region
and is left out when region_code is given. meta.vintage is the latest release
among every record that was ranked, after region_code and exclude_groupings
apply, not only the n returned, since each of them could have changed the order;
for wheat 2023 that is "2026-10", and None when nothing was ranked.
meta.published_at stays empty. Codes and arguments are checked before the call;
a market year without data raises NotFoundError.
Args:
commodity_code: PSD commodity code, seven digits, e.g. "0410000" (Wheat),
"0440000" (Corn), "2222000" (Oilseed, Soybean).
market_year: PSD market year, e.g. 2023, 2022, 2021.
attribute_id: PSD attribute id to rank by, e.g. 28 (Production), 88
(Exports), 57 (Imports), 176 (Ending Stocks);
list_commodity_attributes lists them.
n: How many records to keep, at least 1, e.g. 5, 10 (the default); more
than the countries reporting the attribute returns them all.
region_code: Rank only the countries of this PSD region, as list_countries
gives it, e.g. "R04" (South America), "R18" (East Asia), "R15"
(Africa, NEC and three more, a region list_regions lacks). A code no
packaged country carries is refused; "R00" (World) is one, and the world
total is get_world_data's. Omit (None) for every region.
exclude_groupings: True leaves PSD's aggregates out of the ranking: "E4"
European Union, "E2" EU-15, "E3" EU-25, "C1" Caribbean Basin,
"T3" Africa, NEC, "X8" Southern Asia NEC, "Z7" Other Pacific
Islands, NEC and "ZZ" Other. False, the default, ranks them like
countries.
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>",
"market_year": "<market_year>",
"attribute_id": "<attribute_id>"
},
"name": "usda_psd_get_top_countries"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| n | No | ||
| market_year | Yes | ||
| region_code | No | ||
| attribute_id | Yes | ||
| commodity_code | Yes | ||
| exclude_groupings | No |