canonical: https://jentic.com/apis/ers.usda.gov/ers-usda-gov

# Ers Usda Gov USDA ARMS Data API

Jentic publishes the only available OpenAPI specification for the USDA ARMS Data API, keeping it validated and agent-ready. The Agricultural Resource Management Survey (ARMS) Data API exposes seven endpoints over USDA Economic Research Service survey data covering farm sector financial conditions, production practices, and resource use. The API supports lookups for the reference dimensions (state, year, category, variable, report, farmtype) and a single survey-data query endpoint that returns the underlying observations. Authentication is by api_key query parameter, available free from the USDA developer portal.

## For AI agents

Query USDA Agricultural Resource Management Survey (ARMS) data on farm finances, production practices, and resource use across U.S. states and years. Authenticate with a single api_key query parameter.

## Scope

Does not handle commodity prices, USDA NASS census data, or non-survey administrative records - use for ARMS survey data and reference dimensions only.

## Capabilities

- List the U.S. states covered by the ARMS dataset for use as filter values
- List the survey years covered for use as filter values
- Browse the ARMS variable catalogue to discover queryable measures
- Look up the report taxonomy used to organise survey data
- List the farmtype dimension used to segment results
- Query observation-level survey data filtered by state, year, variable, report, and farmtype
- Inspect the category dimension that organises variables thematically

## Use cases

### Agricultural Sector Research and Reporting

Economists and ag-policy analysts need normalised farm-finance data across states and years to build sector reports. The ARMS API exposes survey observations with reference data lookups, so an agent can pull a clean panel of net farm income, expenses, or asset values without scraping ERS reports or downloading Excel files.

Example prompt: Call GET /surveydata with state=IA, variable=net_cash_farm_income, year=2022 and return the observation set.

### Investor Research on Agriculture-Linked Equities

Investors covering ag-input, machinery, and processor stocks need macro context on the underlying farm sector. The ARMS API provides farm-type segmented financial measures so an agent can correlate sector health with public-company earnings cycles, replacing slow PDF report reading with structured queries.

Example prompt: Call GET /surveydata with farmtype=crop and variable=production_expenses across the last 5 years and return the time series.

### Climate and Resource-Use Studies on U.S. Agriculture

Sustainability researchers need farm resource-use data (inputs, irrigation, land) tied to specific states and years. ARMS reports include resource-use variables that an agent can pull through the /surveydata endpoint, supporting longitudinal studies on agricultural water use, fertiliser, or energy intensity without manual file extraction.

Example prompt: Call GET /report to find resource-use reports, then GET /variable with that report ID and GET /surveydata for variable=irrigated_acres in California.

### AI Agent Agricultural Data Tool via Jentic

An AI research agent can be wired through Jentic to answer questions like 'what was the average net cash farm income in Iowa last year?' on demand. The agent searches by intent, loads the schema for /surveydata, and executes with the api_key scoped from the vault - no manual ARMS file downloads needed.

Example prompt: Use Jentic search('get usda farm income data'), load the GET /surveydata operation, and execute it with state=IA, variable=net_cash_farm_income, year=2022.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | /surveydata | Query ARMS survey observations |
| GET | /state | List available states |
| GET | /year | List available years |
| GET | /variable | List available variables |
| GET | /report | List available reports |
| GET | /farmtype | List farmtype dimension values |
| GET | /category | List variable categories |

## Key resources

- **Survey Data** — Observation-level ARMS data filtered by state, year, variable, report, and farmtype
- **States** — Reference list of U.S. states covered by the ARMS dataset
- **Years** — Reference list of survey years
- **Variables** — Catalogue of measurable variables (income, expenses, assets, resource use)
- **Reports** — Report taxonomy organising variables thematically
- **Farm Types** — Segmentation values for crop, livestock, dairy, and similar farm types
- **Categories** — Higher-level grouping of variables

## Why Jentic

- **Setup:** Wiring the USDA ARMS API by hand means passing your api.data.gov key as the api_key query parameter, learning the variable and report dimension taxonomy, and building your own retries against api.ers.usda.gov. Through Jentic you install once, import the USDA ARMS Data API from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** ARMS is read-only survey data, so scope the agent to the operations it needs, such as GET /surveydata or GET /variable. You pick that allowed set, so an operation like GET /report is only reachable if you include it.
- **Credential handling:** Your api.data.gov key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'get USDA farm income data' or 'list survey variables', and Jentic returns the matching ARMS operation with its input schema so the agent calls the right endpoint without learning the variable and report taxonomy in advance.

## Related APIs

- **U.S. EPA ECHO Clean Air Act** — Federal environmental data - pairs with farm resource-use measures for sustainability research
- **EODHD Financial Data API** — Equity market data - pairs with ARMS farm sector data for ag-linked equity research
- **Escrow.com API** — Escrow service - relevant for high-value farmland or equipment transactions backed by sector research

## FAQ

### Why is there no official OpenAPI spec for the USDA ARMS Data API?

USDA ERS publishes documentation pages but not a downloadable OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call the USDA ARMS Data API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the USDA ARMS Data API use?

The API uses an apiKey scheme passed as the api_key query parameter on every request. The key is free from api.data.gov; through Jentic it is stored encrypted in your Jentic One instance and injected at execution time.

### Can I get farm income data by state with the USDA ARMS Data API?

Yes. GET /surveydata accepts state, year, variable, report, and farmtype filters. To find the income variable identifier, list options with GET /variable first.

### What are the rate limits for the USDA ARMS Data API?

ARMS sits behind api.data.gov, which enforces 1,000 requests per hour per api_key by default and a higher cap on registered keys. Plan polling and bulk pulls within this budget.

### How do I look up available variables through Jentic?

Search 'list usda arms variables'. Jentic returns the GET /variable operation, you load its schema, and execute to receive the variable catalogue. The api_key is injected from the vault.

### Is the USDA ARMS Data API free?

Yes. ARMS data and the API are public-domain U.S. government resources. You only need a free api.data.gov key to access them.

### Can I limit what my agent is allowed to do with the USDA ARMS Data API?

Yes. Because Jentic One is self-hosted, you define the rules that decide which operations and credentials your agent may use, and the ARMS API is read-only survey data. You can scope the agent to only the operations it needs, such as GET /surveydata or GET /variable, so a call like GET /report is reachable only if you include it in the allowed set. Your api.data.gov key stays under your control and is injected at execution time rather than exposed to the agent.