xippios-usda-gats

Typed Python client, MCP server and FastAPI routes for USDA FAS Global Agricultural Trade System, part of the xippios SDK family. Names and semantics follow the upstream documentation; every response carries release metadata (source, endpoint, retrieved_at, published_at, vintage).

Install

uv add xippios-usda-gats            # client only
uv add "xippios-usda-gats[mcp]"     # + MCP server
uv add "xippios-usda-gats[http]"    # + FastAPI router

Set DATA_GOV_API_KEY in the environment. Nothing is read from files.

30-second example

from xippios.usda.gats import get_census_exports, get_census_release_dates
from xippios.usda.gats.models import ProductType

result = get_census_exports("CH", 2026, 8, hs10_code="02")  # US exports to China, August 2026
len(result.data)  # 26: the month's HS10 products of chapter 02, of 777 in all
row = result.data[0]
row.hs10_code, row.value, row.quantity1  # "0201206000", Decimal("30819.0"), Decimal("1018.0")
result.meta.vintage  # "2026-10-06T08:00:00": the month's release time, as upstream states it
result.meta.published_at  # datetime(2026, 10, 6, 8, 0): that time, without a zone
result.meta.published_at_naive  # True: upstream prints its release times without one
result.meta.request  # {"partner_code": "CH", "year": 2026, "month": 8, "hs10_code": "02"}
result.meta.retrieved_at

releases = get_census_release_dates(ProductType.X)  # X exports, M imports
releases.data[0]  # statistical_year_month="202608", release_time_stamp=2026-10-06 08:00 (naive)
this_year = get_census_release_dates(ProductType.X, statistical_year=2026)
len(this_year.data)  # 8: 202608 back to 202601; an unreleased or pre-1967 year gives []

partner_code is GATS's own two-character code, not ISO ("CH" China, "MX" Mexico, "JA" Japan, "IC" Iceland), checked against the countries list packaged in reference/ before any call, since GATS answers an unknown code with an empty list. An unknown code is refused, naming close codes (an ISO or GENC code leads to its partner code first: "CHN" names CH before CN) or pointing to list_countries when none is close. Of the 26 codes GATS marks discontinued (discontinuedOn), the Census tasks refuse the 7 that are no other code's parent for a month after their last, naming the listed codes of the same name and the code's own parent where it has one: "D1" (Denmark) ended in 198712, so 2026-08 is refused and 9U and DA named, while 1987-06 passes. The other 19 are parents, codes other records name as their countryParentCode ("SZ" Switzerland, the parent of SR and LS), and pass for every month, as do the two-digit codes of region R99, "01" (Caribbean,nes) to "18" (ASEAN). month is 1 to 12 and year four digits; hs10_code keeps the products whose code starts with it, a full ten-digit code for one product or a prefix such as a chapter, applied after the one data request. get_census_imports takes the same arguments and adds five consumption and CIF fields per record; get_census_reexports answers the exports' record for US re-exports.

Two parents were recorded for 2026-08, each answering under its own code: "Y1" (Leeward-Windward Islands, discontinued 198801) holds every HS10 code of "AC" (Antigua and Barbuda), one of its nine islands, at no lower a value, as the sum of its children would, and "AS" (Australia, discontinued 198712) answers the 669 records of its child "A2" apart from the code, while "NF" (Norfolk Island), another child, answered none. On that evidence the package accepts every parent for every month. "18" and "01" answered an empty list, which means no data, as for any listed partner without trade; the package assumes no member list for them.

The customs-district forms answer the same partner-month by US customs district, one record per district and HS10 code, and take customs_district_id too, checked against the packaged districts list (an unknown id names the nearest listed ones):

from xippios.usda.gats import get_customs_district_imports

fillets = get_customs_district_imports("IC", 2026, 8, hs10_code="0304", customs_district_id=10)
len(fillets.data)  # 13: fish fillets from Iceland through New York, of 51 in all districts

Each data task makes two requests, a release list and the month, or only the second while the client's cache holds the list, for an hour. The imports forms check the imports list; the exports forms and the re-exports forms check the exports list, the latter by assumption, since upstream publishes no re-export release list. A month the list lacks (not released yet, or before January 1967) raises NotFoundError naming the months released; a listed partner without trade in a released month is an empty list. meta.vintage is the month's release time from that list, as upstream states it ("2026-10-06T08:00:00" for August 2026): upstream's identifier of the release that last revised the figures, since Census applies corrections once a year and the list records only each month's latest release. The month itself is in meta.request and in every record's date. For up to an hour after a release the cached list may still give a revised month the previous release's time, or refuse a month just released, and the refusal says when the list was fetched: an accepted lag. meta.published_at is the same release time parsed and kept without a zone, since FAS states none for its release times, with meta.published_at_naive set; get_census_release_dates returns them as upstream states them, every month's or, with statistical_year, one year's, a filter applied after the one request and recorded in meta.request.

Month series

The three series tasks answer one partner over a range of months, at most 60 in Python and over HTTP and 24 over MCP by default (the ceiling is process-wide, see MCP), as one flat list in month order; every record carries its month in date:

from xippios.usda.gats import get_census_import_series

fish = get_census_import_series("IC", 2026, 7, 2026, 8, hs10_code="03")  # fish from Iceland
len(fish.data)  # 85: 42 records for July, then 43 for August, each month in upstream order
row = fish.data[0]
row.date, row.hs10_code, row.value  # "202607", "0302140003", Decimal("1252640.0")
fish.meta.vintage  # "2026-10-06T08:00:00": the newest release among the months, August's
fish.meta.request  # the six arguments: partner_code, start_year, ..., hs10_code="03"

get_census_export_series, get_census_import_series and get_census_reexport_series take partner_code, start_year, start_month, end_year, end_month and hs10_code, which filters every month. Everything is checked before the first request, the partner code for the start and for the end month, so a code discontinued inside the range that is no other code's parent is refused ("D1" for 1987-06 to 1988-01 names 198712), while a parent code passes for every month; a start after the end, or a range longer than the ceiling in force, is refused too, naming the ceiling. The flow's release list is read once, and every month of the range must be in it: a range ending in a month not released yet raises NotFoundError naming that month and the latest released, rather than returning the months that are. meta.vintage is the newest release time among the range's months, which across Census's annual revision can be an earlier month's than the end month's (2025-12 to 2026-02 gives December's revised 2026-06-24T08:00:00); get_census_release_dates has each month's own.

Pacing. A series spends one keyed request per month, plus the release list unless the client's cache holds it, and sends them one after another at the client's pace of one request per second, never at once: 60 months take about a minute and 60 of the key's 1,000 requests per hour. A quota spent partway raises RateLimitError, and none of the months is returned.

UN Trade data

The UN half of GATS is frozen. As recorded on 2026-10-26, both UN Trade release lists end with statistical year 2019, and their newest release is dated 2021-01-18: no later year has appeared since. The package wraps this data faithfully, as GATS serves it, so that a product-level comparison with UN Comtrade is possible elsewhere; it maps no code. Reporter, partner and HS6 codes stay GATS's own (list_countries, list_hs6_commodities), not UN Comtrade's and not ISO.

GATS serves trade "as reported by UN COMTrade", one reporter and one statistical year per request, one record per partner and HS6 code:

from xippios.usda.gats import get_un_exports, get_un_release_dates
from xippios.usda.gats.models import ProductType

fish = get_un_exports("IC", 2019, hs6_code="03")  # Iceland's 2019 exports, HS chapter 03
len(fish.data)  # 1024 records, partner by partner, of 3,980 for the whole year
row = fish.data[0]
row.partner_country_code, row.hs6_code, row.value  # "AE", "030211", Decimal("10620.0")
fish.meta.vintage  # "2020-06-03T05:50:46": Iceland 2019's release time in the exports list
fish.meta.request  # {"reporter_code": "IC", "year": 2019, "hs6_code": "03"}: the filters given

coverage = get_un_release_dates(ProductType.X, reporter_code="IC")
[r.statistical_year for r in coverage.data]  # ["2019", "2018", ..., "1989"]: 31 years

get_un_exports, get_un_imports and get_un_reexports take reporter_code, year and two filters applied after the one data request, partner_code (exact) and hs6_code (a full code from the packaged HS6 list, or a prefix of 1 to 5 digits). The records keep GATS's codes as the data carries them, older ones included: the countries list marks AS (Australia), DA (Denmark), IT (Italy), NO (Norway) and NZ (New Zealand) discontinued in 1987, yet the UN data uses them for later years and never their same-name successors (A2, N3, ...). So the UN tasks check both country codes for membership in the packaged list only; the Census tasks' discontinuation rule does not apply. An ISO or GENC code that several listed codes share is refused naming first the codes the flow's UN release list holds as reporters: "AUS" names AS before A2, "FRA" names F1 before FR. The lists follow no rule on the codes themselves (the parent reports for Australia, its child for France, both for Germany), so such a refusal reads the list first, still before the data request, and comes unranked when the list cannot be read; the Census tasks keep the current code first. Before the data request a task checks the reporter-year against the flow's UN release list, which the client keeps for a day, the feed being frozen: the imports task the imports list, the exports task and, by assumption, the re-exports task the exports list, since upstream publishes no re-export list. GATS answers an unknown reporter, a future year and an unreleased year alike with an empty list, so a reporter-year the list lacks raises NotFoundError naming the reporter's listed years and the latest year; a listed reporter-year without trade is an empty list (Iceland's 2019 re-exports). meta.vintage is the reporter-year's release time as upstream states it, and meta.published_at that time parsed, naive, as for the Census tasks. One reporter-year can be large: Iceland's 2019 imports are 23,396 records (about 5.2 MB), India's 2016 exports 75,919 (about 17 MB). get_un_release_dates(product_type, reporter_code=None, year=None) returns either list, one record per reporter and year, 3,796 for exports and 3,832 for imports as recorded.

Reference lists

Five GATS lists ship with the package under reference/, and their list_* tasks answer from them without a call; meta.retrieved_at is when the package fetched the list, and meta.vintage stays empty, since upstream gives the lists no version:

from xippios.usda.gats import list_countries, list_hs6_commodities
from xippios.usda.gats.enums import UnitOfMeasureId

list_countries(search="CHN").data  # [Country(country_code="CH", ..., iso3_code="CHN", ...)]
list_countries(region_code="R05").data  # CA, GL, MX, SB, US (North America)
list_hs6_commodities(hs6_code="0201").data  # the three HS6 codes of heading 0201
UnitOfMeasureId.KILOGRAMS  # 47, the unit id of the data records

list_regions() (15), list_countries(region_code=None, search=None) (322 codes, current and discontinued; search on the code, the name, the ISO and the GENC code), list_hs6_commodities(search=None, hs6_code=None) (2,909; search on the code, the name and the description, hs6_code a prefix of the code, as list_commodities' hs10_code), list_units_of_measure() (108, ids 0 to 107, which enums.UnitOfMeasureId names) and list_customs_districts() (53, e.g. 10 NEW YORK, N.Y.).

The HS10 list is not packaged: 24,936 records and about 7.6 MB. list_commodities(search=None, hs10_code=None, product_type=None) fetches it live, in one request the client keeps for a day and parses into records once for that day, and filters it: search on the name and the description, hs10_code a prefix of the code, product_type exact. Upstream's product types are "X" (exports, 5,919 records), "M" (imports, 14,469), "T" (2,704) and "B" (1,844); upstream documents none of them, and the T and B records carry seven-digit codes padded with three spaces, kept as sent. On a cache hit meta.retrieved_at is when the list was fetched.

MCP

{
  "mcpServers": {
    "usda-gats": {
      "command": "uvx",
      "args": ["--from", "xippios-usda-gats[mcp]", "xippios-usda-gats-mcp"],
      "env": { "DATA_GOV_API_KEY": "..." }
    }
  }
}

Tools are read-only and named usda_gats_<verb>_<noun>. Results are capped, at 200 rows or 64 KB unless a tool has a cap of its own, with a note on the rows left out that names the tool's filters: one partner-month is one row per HS10 product (777 rows for exports to China in August 2026, 3,294 for imports, 1,697 by customs district), so the notes of the Census data tools name hs10_code, and those of the customs-district tools customs_district_id too, while the series tools' notes say the rows run oldest month first and name hs10_code and fewer months; usda_gats_list_hs6_commodities names search and hs6_code, usda_gats_list_commodities its three filters. The UN Trade data tools name partner_code and hs6_code (one reporter-year is one row per partner and HS6 code, 3,980 rows for Iceland's 2019 exports), and usda_gats_get_un_release_dates names reporter_code and year (3,796 reporter-years in the exports list). usda_gats_list_countries has a cap of its own, 400 rows or 100,000 bytes, so its 322 codes arrive whole. usda_gats_get_census_release_dates returns the newest 200 months, more than sixteen years, with a note that says so and names statistical_year, which keeps one year's months. --http serves streamable HTTP instead of stdio.

--series-months MONTHS sets the most months one series tool call spans, a whole number from 1 to 60. The server starts with 24: two years, 24 requests, about 24 seconds at the client's pace of one request per second. The Python API and the HTTP router allow 60, five years and about a minute (tasks.SERIES_MAX_MONTHS). A longer range is refused before any request, with a message that names the ceiling in force and, below 60, --series-months; a value outside 1 to 60 stops the server at start with exit status 2. For five-year series over MCP, append "--series-months", "60" to the args above.

The entry point xippios-usda-gats-mcp sets the 24, or the --series-months given: core's main applies the option through the hooks tasks.mcp_add_options and tasks.mcp_apply_options. A host that imports xippios.usda.gats.mcp.server and serves it another way applies no option and keeps 60. The ceiling is process-wide (tasks.series_ceiling(), tasks.set_series_ceiling(months)), so a Python or HTTP call made inside an MCP server's process meets the MCP ceiling too: one ceiling, and one MCP server, per process.

Status

All nineteen operations of the snapshot (docs/upstream/) are wrapped. 0.2.0 covers them with the same twenty tasks as 0.1.0, the first release: six Census data tasks, three month series, the Census release dates, four UN Trade tasks and six list tasks. Alpha: the public surface may change in a minor version before 1.0 (conventions §12); CHANGELOG.md lists every change. The UN Trade tasks wrap a frozen series (conventions §4): their rows name the feed's last release, 2021-01-18, as recorded on 2026-10-26.

Every request counts against api.data.gov's quota of 1,000 requests per hour per key, shared by every package using the same DATA_GOV_API_KEY (xippios-usda-psd and xippios-usda-esr among them); an answer from the client's cache spends none. The client caches five answers and nothing else: the two Census release lists for an hour, the two UN Trade release lists for a day, since that feed is frozen, and the HS10 commodities list for a day; it stores a body of up to 16 MiB, twice core's default, so that the 7.6 MB commodities list stays cached if it grows. A month series spends one request per month. The client keeps its own pace of one request per second; once the quota is spent it waits for the quota to come back when that takes at most 30 s, and otherwise raises RateLimitError with retry_after instead of sending.

Upstream terms and attribution

Data comes from USDA FAS Global Agricultural Trade System (https://apps.fas.usda.gov/gats/default.aspx) under its own terms of use; this package adds no rights to it. Documentation snapshot: docs/upstream/.

Licence

Apache-2.0. See LICENSE.