USDA APIdata.ers.usda.gov ↗
Access county-level unemployment, income, poverty, demographics, and rural classifications for all 3,143 US counties via the USDA ERS Rural Atlas API.
What is the USDA API?
This API exposes economic, demographic, and classification data for all 3,143 US counties from the USDA Economic Research Service Rural Atlas, spread across 5 endpoints. get_county_economic_data returns unemployment rates for 2007–2021, per capita income, median household income, and poverty rates. get_county_classifications returns rural-urban continuum codes, metro/nonmetro status, and economic dependency types. All endpoints accept FIPS-based filters at the state or county level.
curl -X GET 'https://api.parse.bot/scraper/c7b74021-b401-4802-835a-401aee92b836/get_county_economic_data?limit=2&state_fips=06&county_fips=06037' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace data-ers-usda-gov-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: USDA ERS County Economic Data API — bounded, re-runnable."""
from parse_apis.usda_ers_county_economic_data_api import UsdaErs, Service, CountyNotFound
client = UsdaErs()
# Construct a county by FIPS and fetch economic data.
la_county = client.county(fips="06037")
econ = la_county.economics(limit=1).first()
if econ:
print(f"{econ.county}, {econ.state}: unemployment 2021={econ.unemployment.rate_2021}%, "
f"median income=${econ.income.median_household_income}")
# Fetch demographics for the same county.
demo = la_county.demographics(limit=1).first()
if demo:
print(f"Population: {demo.population.estimate_2021}, "
f"College+: {demo.education.college_plus_pct}%")
# Fetch classifications to check metro/rural status.
cls = la_county.classifications(limit=1).first()
if cls:
print(f"Metro: {cls.metro_2013}, High amenity: {cls.high_amenity}, "
f"Rural-urban code: {cls.rural_urban_continuum_code_2013}")
# Discover available layers for a service, then query raw data.
people_svc = client.dataservice(name="people")
layer = people_svc.list_layers(limit=3).first()
if layer:
print(f"Layer {layer.id}: {layer.name} (service={layer.service})")
# Typed error handling: attempt a lookup for a non-existent county.
bogus = client.county(fips="99999")
try:
result = bogus.economics(limit=1).first()
print(f"Result: {result}")
except CountyNotFound as exc:
print(f"County not found: {exc.county_fips}")
print("exercised: county.economics / county.demographics / county.classifications / "
"dataservice.list_layers / CountyNotFound")
Get comprehensive economic data for counties including unemployment rates (2007-2021), employment change, employment by industry sector, median household income, per capita income, and poverty rates. Combines Jobs and Income data services. Without filters returns all ~3,143 US counties. Pagination is internal; the response is a single page.
| Param | Type | Description |
|---|---|---|
| limit | integer | Maximum number of counties to return. If omitted, returns all matching counties. |
| state_fips | string | 2-digit state FIPS code to filter by state (e.g., '01' for Alabama, '06' for California). Leading zeros preserved. |
| county_fips | string | 5-digit county FIPS code for a specific county (e.g., '06037' for Los Angeles County). Leading zeros preserved. |
{
"type": "object",
"fields": {
"filter": "object with state_fips and county_fips filter values",
"counties": "array of county objects with fips, state, county, unemployment (rates 2007-2021), employment_change (percent changes), employment_by_industry (10 sectors), income (median_household_income, per_capita_income), poverty (poverty_rate, child_poverty_rate, deep_poverty_rate, deep_child_poverty_rate)",
"total_counties": "integer total count of returned counties"
}
}About the USDA API
Economic and Income Data
The get_county_economic_data endpoint combines Jobs and Income data layers into a single county-level response. Fields include annual unemployment rates from 2007 through 2021, employment change as a percent, employment breakdowns by industry sector, median household income, per capita income, and poverty rates. Filter by state_fips (2-digit, e.g. '06' for California) or county_fips (5-digit, e.g. '06037' for Los Angeles County). All FIPS codes preserve leading zeros.
Demographics
get_county_demographics returns population estimates, density, and change rates alongside net migration, natural change, and international migration figures. Age distribution, race and ethnicity breakdowns, education attainment levels, household characteristics, and foreign-born population share are all included in the county objects. The same state_fips and county_fips filters apply, and omitting both returns data for all counties.
County Classifications
get_county_classifications surfaces the USDA's official typology codes: rural_urban_continuum_code_2013, urban_influence_code_2013, metro/nonmetro designation, and economic dependency classifications such as farming, manufacturing, mining, government, and recreation. Special designations like low employment, population loss, and retirement destination counties are also included. These codes are widely used in rural policy research.
Layer Discovery and Raw Queries
list_available_layers enumerates all available layers across five services — People, Jobs, Income, County_Classifications, and Veterans — returning each layer's id, name, and default_visibility. The query_layer endpoint lets you pull raw attribute data from any specific layer by passing the service name and an optional layer_id. Response field names vary by layer, so using list_available_layers first is the practical way to know what fields a given layer exposes.
The USDA API is a managed, monitored endpoint for data.ers.usda.gov — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when data.ers.usda.gov changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official data.ers.usda.gov API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Map county-level unemployment trends from 2007 to 2021 to identify regions still recovering from the 2008 recession
- Filter nonmetro counties by economic dependency type (farming, mining, recreation) for rural development grant targeting
- Join per capita income and poverty rate fields with census geometries for choropleth mapping
- Identify retirement-destination counties using classification flags for demographic research
- Compare net migration and natural population change across states to analyze rural population loss
- Pull Veterans service layer data alongside income figures to assess economic conditions for veteran populations
- Build a county comparison tool using FIPS-filtered queries across economic, demographic, and classification endpoints
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does USDA ERS have an official developer API?+
How do I retrieve data for a single county using get_county_economic_data?+
county_fips parameter, for example '06037' for Los Angeles County. The response returns a counties array with one object containing unemployment rates, income fields, and employment sector data for that county, plus a total_counties count of 1. You can also pass only state_fips to get all counties within a state.What time period does the unemployment data cover?+
get_county_economic_data endpoint returns unemployment rates spanning 2007 through 2021. Data for years before 2007 or after 2021 is not currently available through this endpoint. You can fork this API on Parse and revise it to target a different layer if more recent ERS data layers become available.Does the API include city-level or census-tract-level data?+
What does the query_layer endpoint return, and when should I use it instead of the named endpoints?+
query_layer when you need data from a specific layer not surfaced by the three named endpoints — particularly Veterans data or any layer with unusual fields. Pass the service name (e.g. veterans) and a layer_id from list_available_layers. The response includes a counties array of raw attribute objects; field names vary by layer and are not normalized across services.