# USDA Foreign Agricultural Service — Open Data Services

> The Foreign Agricultural Service (FAS) is the export-and-trade agency of the U.S. Department of Agriculture. Its Open Data Services publish three public HTTPS/JSON datasets on U.S. and world agricultural trade: ESR (weekly U.S. export sales of agricultural commodities), GATS (the Global Agricultural Trade System, carrying U.S. Census and UN ComTrade import/export/re-export data), and PSD (Production, Supply and Distribution forecasts for world agricultural commodities). All 35 operations are read-only GETs behind a single free API key sent in an `API_KEY` request header.

This file was GENERATED by API Evangelist from the provider's own published contract and portal. USDA FAS does not publish an llms.txt: https://www.fas.usda.gov/llms.txt returns 404 and https://apps.fas.usda.gov/llms.txt returns 404 (probed 2026-09-10).

## APIs

- [FAS Open Data Services — Swagger 2.0 contract](https://apps.fas.usda.gov/opendata/swagger/docs/v1): The machine-readable contract, served live by the provider. 35 operations, 3 datasets, `basePath: /OpenData`, `securityDefinitions.apiKey` = header `API_KEY`.
- [Swagger UI reference](https://apps.fas.usda.gov/opendata/swagger/ui/index): The provider's interactive API reference, rendering the contract above.
- [OpendataWeb portal](https://apps.fas.usda.gov/opendataweb/home): The developer portal — home, about, contact and API-key signup.
- Base URL: `https://apps.fas.usda.gov/OpenData`

## Datasets

- **ESR — Export Sales Reporting** (7 operations): weekly U.S. export sales by commodity, country and market year. Reference lookups for regions, countries, commodities and units of measure; `ESRData_GetDataReleaseInfo` tells you which commodity/market-year combinations currently have data.
- **GATS — Global Agricultural Trade System** (19 operations): U.S. Census exports, imports and re-exports by partner country, year and month; the same three by customs district; UN ComTrade exports, imports and re-exports by reporter country and year; commodity lookups at both the FAS and 6-digit Harmonized System levels.
- **PSD — Production, Supply and Distribution** (9 operations): world agricultural commodity forecasts by commodity, country and market year, plus a world roll-up and the attribute list (production, exports, ending stocks and the rest).

## Getting started

1. Request a free API key from the portal signup page: https://apps.fas.usda.gov/opendatawebv2/#/signup — the form is the api.data.gov signup widget (`api.data.gov/static/javascripts/signup_embed.js`) embedded in the FAS portal.
2. Send the key on every request as the `API_KEY` HTTP header. It is not a query parameter and not a bearer token.
3. Call e.g. `GET https://apps.fas.usda.gov/OpenData/api/psd/commodities` with that header.

Observed behaviour without a valid key (probed 2026-09-10): a missing key returns HTTP 403 with the bare JSON body `"Bad API Key"`; a malformed key returns HTTP 500 with `{"message":"An error has occurred."}`. Neither is RFC 9457 problem+json.

## Specs and artifacts (API Evangelist)

- [Harvested Swagger 2.0](openapi/_original/foreign-agricultural-service-fas-open-data-swagger.json): the provider's contract, saved verbatim.
- [ESR OpenAPI](openapi/foreign-agricultural-service-esr-api-openapi.yml) · [GATS OpenAPI](openapi/foreign-agricultural-service-gats-api-openapi.yml) · [PSD OpenAPI](openapi/foreign-agricultural-service-psd-api-openapi.yml): one refined OpenAPI 3.2 document per dataset, carrying the provider's real operationIds.
- [Authentication](authentication/foreign-agricultural-service-authentication.yml) · [Conventions](conventions/foreign-agricultural-service-conventions.yml) · [Error catalog](errors/foreign-agricultural-service-problem-types.yml) · [Lifecycle](lifecycle/foreign-agricultural-service-lifecycle.yml) · [Data model](data-model/foreign-agricultural-service-data-model.yml) · [Conformance](conformance/foreign-agricultural-service-conformance.yml)
- [Agent skills](skills/_index.yml) · [Candidate MCP tool shape](mcp/foreign-agricultural-service-mcp.yml) — FAS operates no MCP server; that file is a derived candidate, not a live endpoint.

## Policies and contact

- [FAS Data and Analysis](https://www.fas.usda.gov/data): the agency's data landing page.
- [Portal contact form](https://apps.fas.usda.gov/opendatawebv2/#/contact) — technical questions go to the FAS Web Admin Team.
- [USDA Privacy Policy](https://www.usda.gov/privacy-policy)
- [USDA Vulnerability Disclosure Policy](https://www.usda.gov/vulnerability-disclosure-policy) — run as a Bugcrowd program at https://bugcrowd.com/engagements/usda-vdp.
- [FAS Information Quality](https://www.fas.usda.gov/information-quality) · [FAS FOIA](https://www.fas.usda.gov/freedom-information-act-foia)

## What FAS does not publish

Recorded so an agent does not go looking: no client SDK in any registry, no CLI, no sandbox or test-key mode, no webhooks or AsyncAPI, no dated changelog, no status page, no `/.well-known/` documents on any host, no A2A agent card, no MCP server, and no published rate limits or rate-limit response headers.