xippios-usda-wasde

Typed Python client, MCP server and FastAPI routes for USDA WAOB World Agricultural Supply and Demand Estimates, 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-wasde            # client only
uv add "xippios-usda-wasde[mcp]"     # + MCP server
uv add "xippios-usda-wasde[http]"    # + FastAPI router

It depends on xippios-usda-esmis, installed with it, to list WASDE's releases in ESMIS's catalog and to download their files; this package's server serves its own tools only.

No API key is needed.

30-second example

from datetime import date

from xippios.usda.wasde import (
    get_balance_sheet,
    get_latest_release,
    get_release,
    list_commodities,
    list_releases,
    read_report_text,
)

latest = get_latest_release()  # the newest WASDE release in ESMIS
latest.data.id, latest.data.month  # "796099", "2026-10"
latest.meta.published_at  # 2026-10-09 12:00:00: ESMIS's printed time, no zone (ADR-0022)

releases = list_releases(since=date(2026, 1, 1))  # bound it: without since, 29 requests
[release.month for release in releases.data if release.revision]  # ["2026-06", "2026-05"]

page_12 = list_commodities(search="sr12")  # packaged with the package: no request
[row.commodity for row in page_12.data]  # ["FEED GRAINS", "CORN"]: matrix1 and matrix2

corn = get_balance_sheet("CORN")  # page 12's U.S. corn matrix, read from the latest XML
corn.meta.endpoint, corn.meta.vintage, len(corn.data)  # "wasde1026.xml", "October 2026", 60
corn.data[0].attribute, corn.data[0].cell_value  # "Area Planted", "90.9" (2024/25)
# its subtitle and footnotes are page 12's in list_tables(search="sr12"), stated once

october = get_release("2026-10")  # Python only: every value, 6543 records, one download
narrative = read_report_text("2026-10")  # the XLS's sheet WASDE Text, one string a paragraph
narrative.data[1][:6]  # "WHEAT:"

Each record of get_release is one value of the release's tables with the labels its page prints, as printed (WasdeXmlCell): 6543 for October 2026, pages 8 to 37. unit is what the file states: the subtitle of the world and summary pages (8 to 10, 18 to 30), the label of a reliability table for its average, smallest and largest; on the U.S. pages it is None, since the XML does not say which of its repeated unit rows the page shows (the XLS and the TXT print them in place). list_tables, list_commodities and list_regions answer from lists packaged with the package, read from the October 2026 release's files (ESMIS release 796099) by scripts/refresh_reference.py (reference/README.md) and refreshed before each release: its 30 table pages with their titles, subtitles and footnotes, the 43 supply-and-use matrices of pages 11 to 30, 32 and 33 with their commodities, and its 70 region texts, as printed. The XML names none of these matrices' commodities as a whole: on pages 12 to 15 they are the XLS's block titles; only page 32's records carry a commodity, one per row (e.g. Beef, Pork, Broiler, Turkey, Red Meat & Poultry), while the list names its matrix Meats, so list_commodities(search="beef") answers nothing.

get_table and get_balance_sheet answer a slice of get_release's records, a page or one commodity's matrix, the world pages' rows of one region, named as the packaged lists name them ("CORN" is page 12's U.S. corn, "Corn" the world corn pages; "Argentina" matches " Argentina"). Their records (WasdeTableValue) leave out the page's own labels: its subtitle and footnotes, to which a marker such as Trade 2/ refers, are list_tables's, stated once per page with its titles, the page's number line ( WASDE - 676 - 12) is left out, and the report month is meta.vintage. So every page and balance sheet of October 2026 fits its tool's cap (get_table 400 rows or 128 KB, get_balance_sheet 300 rows or 128 KB), each with a note that says how to see the rest should one not. Each call downloads the month's XML and keeps nothing, so a Python caller wanting several slices of one month calls get_release once.

read_report_text answers the narrative as text, from the XLS's sheet WASDE Text, or from the PDF's narrative pages for a release without an XLS or whose XLS has no such sheet; no figure is ever read from a PDF. meta.vintage is the month the XLS prints, or for a PDF, which prints a date, the ESMIS release id. Task functions are listed in the status table below.

MCP

{
  "mcpServers": {
    "usda-wasde": {
      "command": "uvx",
      "args": ["--from", "xippios-usda-wasde[mcp]", "xippios-usda-wasde-mcp"]
    }
  }
}

Tools are read-only and named usda_wasde_<verb>_<noun>. Results are capped, at 200 rows or 64 KB unless a tool has a cap of its own, with a note on how to see the rest. --http serves streamable HTTP instead of stdio.

Status

Upstream terms and attribution

Data comes from USDA WAOB World Agricultural Supply and Demand Estimates (https://www.usda.gov/oce/commodity/wasde), on whatever terms upstream states for it, if any; this package adds no rights to it. Documentation snapshot and its attribution: docs/upstream/FETCHED.md.

Licence

Apache-2.0. See LICENSE.