# Economic Research Service (USDA ERS) > The Economic Research Service is the United States Department of Agriculture's economic > research and statistics agency, covering agriculture, food, rural economies and the farm > sector. It publishes two public API surfaces: the ARMS Data API, which serves Agricultural > Resource Management Survey values as JSON through the shared Federal api.data.gov gateway, > and a set of ArcGIS geospatial map and feature services that back the ERS atlases. Both are > free, read-only United States Government public data. ## What an agent needs to know first - There is NO OpenAPI, Swagger or JSON Schema for the ARMS Data API. Probing https://api.ers.usda.gov/openapi.json, /openapi.yaml, /swagger.json, /api-docs and /docs all returned 404. The API is documented in prose only. - The ARMS API DOES self-describe at runtime: HTTP OPTIONS on each resource returns that endpoint's schema and input requirements. This requires a key - OPTIONS anonymously returns 403 API_KEY_MISSING. - The geospatial surface is the machine-readable one. Every ArcGIS service publishes its own layers, fields, geometry and capabilities at ?f=json, and seventeen map services publish a full WSDL 1.1 / SOAP contract with 55 operations each. No key needed. - Everything is read-only. There is no write, no mutation, no idempotency concern and nothing to reverse. - There is no versioning of any kind. One breaking response-shape change shipped in 2019 with no notice window. ## APIs - [USDA ERS Data APIs (ARMS)](https://www.ers.usda.gov/developer/data-apis/arms-data-api): Agricultural Resource Management Survey data as JSON. REST base https://api.ers.usda.gov/data/ plus a GraphQL endpoint at https://api.ers.usda.gov/data/arms/graphql. Requires a free api.data.gov key. - [USDA ERS Geospatial APIs](https://www.ers.usda.gov/developer/geospatial-apis): 25+ ArcGIS map and feature services on https://gisportal.ers.usda.gov/server/rest/services backing the Atlas of Rural and Small-Town America, the Food Environment Atlas and the Food Access Research Atlas. Anonymous. ## ARMS resources One fact resource and six dimension resources. The dimensions exist to enumerate the legal values of the fact resource's parameters, so an agent can discover the entire vocabulary before composing a query. - `GET /arms/year` — every year with data (1996 to present). - `GET /arms/state` — all States, with per-State metadata and available variables. - `GET|POST /arms/report` — the eight tailored reports (Farm Business Balance Sheet, Farm Business Income Statement, Farm Business Financial Ratios, Structural Characteristics, Farm Business Debt Repayment Capacity, Government Payments, Operator Household Income, Operator Household Balance Sheet). - `GET|POST /arms/variable` — the measures, searchable by ID, report, name or keyword. - `GET|POST /arms/category` — breakdown axes: Economic Class (sal), Farm Typology (ftyppl), Operator age (age), Farm Resource Region (reg), NASS region (n5reg), Production Specialty (spec). - `GET|POST /arms/farmtype` — farm types, searchable by name, ID or keyword. - `GET|POST /arms/surveydata` — the values. `year` is required; at least one of `report` or `variable` is required; `state`, `category`, `category_value`, `category2` and `farmtype` are optional. Query syntax: multi-value fields are comma-separated; multi-word values use `+` for the space. Example: `?year=2015,2016&state=all&report=income+statement&farmtype=operator+households`. ## Authentication - ARMS: a free api.data.gov key, obtained at https://api.data.gov/signup/ with a name and an email address, delivered automatically. Pass it as `?api_key=`, the `X-Api-Key` header, or the HTTP basic auth username. One key covers every agency on api.data.gov and shares one quota across all of them. - api.data.gov publishes `DEMO_KEY` for exploring before signing up: 30 requests per hour and 50 per day, per IP address. ERS does not mention it. - Geospatial: none. The published ArcGIS services answer anonymously. - A missing key returns HTTP **403** (not 401) with no WWW-Authenticate header. ## Rate limits - 1,000 requests per hour per key, rolling window, across all api.data.gov APIs. - `X-RateLimit-Limit` and `X-RateLimit-Remaining` on every response. No reset header and no `Retry-After`. - Exhaustion returns HTTP 429 with error code `OVER_RATE_LIMIT`. - The geospatial services publish no rate limits, but do publish ceilings per service: maxRecordCount 2000, maxImageWidth/Height 4096. ## Errors Envelope is `{"error": {"code": "...", "message": "..."}}` as `application/json` — NOT RFC 9457 problem+json. Codes are the api.data.gov gateway's: `API_KEY_MISSING`, `API_KEY_INVALID`, `API_KEY_DISABLED`, `API_KEY_UNAUTHORIZED`, `API_KEY_UNVERIFIED`, `HTTPS_REQUIRED`, `OVER_RATE_LIMIT`, `NOT_FOUND`. Key on the status code or `error.code`, never the message text. ERS publishes no catalog for errors raised past the gateway by ARMS itself. ## Terms an integrator must honour Any application using the API must display, prominently: "This product uses the ERS Data API but is not endorsed or certified by ERS." You may not modify or misrepresent content and still attribute it to ERS. See https://www.ers.usda.gov/developer/api-terms-of-service. ## What ERS does not publish - No OpenAPI, no AsyncAPI, no JSON Schema, no GraphQL SDL. - No webhooks, no events, no streaming. - No MCP server and no A2A agent card. `/.well-known/` is empty on every ERS host (42 paths probed across six hosts, all 404). - No `llms.txt`, no status page, no SLA, no deprecation policy, no versioning scheme. - No OGC WMS or WFS on the geospatial services — the extensions are not enabled. - No client SDK on any registry. Code samples on GitHub were last touched in 2013. ## Documentation - [Developer home](https://www.ers.usda.gov/developer/) - [Data APIs](https://www.ers.usda.gov/developer/data-apis) - [ARMS Data API reference](https://www.ers.usda.gov/developer/data-apis/arms-data-api) - [ARMS updates and revisions (changelog)](https://www.ers.usda.gov/developer/data-apis/arms-data-api/updates-and-revisions) - [Geospatial APIs](https://www.ers.usda.gov/developer/geospatial-apis) - [API Terms of Service](https://www.ers.usda.gov/developer/api-terms-of-service) - [api.data.gov developer manual](https://api.data.gov/docs/developer-manual/) - [ArcGIS REST services directory](https://gisportal.ers.usda.gov/server/rest/services) - [ERS on GitHub](https://github.com/USDA-REE-ERS) - [Amber Waves (ERS magazine)](https://www.ers.usda.gov/amber-waves) ## This profile Independent third-party profile maintained by API Evangelist. Artifacts in this repository: `wsdl/` (three verbatim SOAP contracts plus a nineteen-endpoint probe index), `conformance/`, `authentication/`, `conventions/`, `errors/`, `lifecycle/`, `changelog/`, `rate-limits/`, `plans/`, `packages/`, `components/`, `data-model/`, `sandbox/`, `mcp/` (a candidate tool list — no server exists), `well-known/`, `security/`.