---
name: usda-ers-arms-api-ingestion
description: "How to get USDA ERS ARMS Data API data into a pandas DataFrame and Parquet: access, the request, the format, limits, quirks and terms."
---

# Load USDA ARMS survey estimates into pandas and Parquet

Source entry: https://signal-lab-jet.vercel.app/datasets/usda-ers-arms-api
Provider: https://www.ers.usda.gov/developer/data-apis/arms-data-api
Checked against the provider's documentation: 2026-11-01

## Access
- Register a valid email address for a free data.gov API key and set USDA_ERS_API_KEY.
- The REST surveydata endpoint requires year plus either report or variable.

## Request
```bash
curl 'https://api.ers.usda.gov/data/arms/surveydata?api_key=$USDA_ERS_API_KEY&year=2023&report=income+statement&state=all'
```

## Format
JSON response containing ARMS survey estimates and query metadata; survey rows include dimensions, values, standard errors and display precision fields.

## Load into pandas and Parquet
Needs Python 3 with requests, pandas and pyarrow.
```python
"""USDA ARMS income-statement estimates -> pandas -> Parquet. Free API key required."""
import os
import requests
import pandas as pd

URL = "https://api.ers.usda.gov/data/arms/surveydata"
params = {
    "api_key": os.environ["USDA_ERS_API_KEY"],
    "year": "2023",
    "state": "all",
    "report": "income statement",
}
r = requests.get(URL, params=params, timeout=60)
r.raise_for_status()
payload = r.json()
rows = payload.get("data", payload)
if isinstance(rows, dict):
    rows = rows.get("data", rows.get("results", []))
df = pd.DataFrame(rows)
df.to_parquet("usda_arms_income_statement_2023.parquet", index=False)
print(len(df), "ARMS estimates", len(df.columns), "columns")
```
Not run: it needs a free API key.

## Limits
- Rate limit: Not stated.
- A free data.gov API key is required.
- surveydata requires year and at least one of report or variable.

## Quirks
- Keep standard-error and decimal-display fields with each estimate.
- Farm-typology labels have separate 1996–2011 and 2012-present definitions.
- Historical records can be revised in later annual database releases.

## Terms and attribution
- ERS permits services that search, display, analyze, retrieve and view API data.
- Applications using the API should display ERS's specified non-endorsement notice.
- Terms page: https://www.ers.usda.gov/developer/api-terms-of-service

## Sources
- https://www.ers.usda.gov/developer/data-apis/arms-data-api: "The data in the API are available in JSON format and provide attribute-based querying."
- https://www.ers.usda.gov/developer/data-apis/arms-data-api: "Users of the ARMS data API are required to sign up for an API key"
- https://www.ers.usda.gov/developer/data-apis/arms-data-api/updates-and-revisions: "A database update was released on December 18, 2024, containing new data from 2023 and additional data from prior years."
- https://www.ers.usda.gov/developer/api-terms-of-service: "This product uses the ERS Data API but is not endorsed or certified by ERS."

## Help improve this skill
Missing a source, or see something to improve? Call the MCP tool suggest_source or feedback (or POST /api/suggest or /api/feedback). Reviewed ideas: https://signal-lab-jet.vercel.app/agent-suggestions

Information for educational purposes only. Free tiers, limits and licenses belong to the providers and may change; check the provider's own terms before using the data.