USDA APInass.usda.gov ↗
Access USDA NASS QuickStats parameter discovery, publications calendar, and Cropland Data Layer download links via 3 structured endpoints. No API key required.
What is the USDA API?
This API exposes 3 endpoints covering USDA National Agricultural Statistics Service (NASS) data: parameter discovery for the QuickStats database, a publications calendar, and Cropland Data Layer (CDL) download links. The quickstats_discover_params endpoint returns all accepted values for any QuickStats filter parameter — sector, commodity, state, statistic category, and more — without requiring a NASS API key. Coverage spans crop production, livestock, farm economics, and geospatial land-use layers from 2008 onward.
curl -X GET 'https://api.parse.bot/scraper/55100b29-3e49-45e3-89e0-bfb55ac41e47/quickstats_discover_params?sector_desc=ANIMALS+%26+PRODUCTS&target_param=sector_desc' \ -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 nass-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 NASS data discovery — sectors, commodities, calendar, CDL."""
from parse_apis.usda_nass_quickstats_publications_api import (
NASS, Sector, ParameterNotFound
)
client = NASS()
# 1. Discover all available sectors in QuickStats
sectors = client.parameterdiscoveries.discover(target_param="sector_desc")
print(f"Parameter: {sectors.parameter}")
for val in sectors.values:
print(f" Sector: {val.value} — {val.label}")
# 2. Discover commodity groups within the CROPS sector using the enum
crops_groups = client.parameterdiscoveries.discover(
target_param="group_desc", sector_desc=Sector.CROPS
)
print(f"\nCROP groups found: {len(crops_groups.values)}")
for val in crops_groups.values[:3]:
print(f" {val.label}")
# 3. Retrieve the publications calendar for a specific month
calendar = client.publicationscalendars.get(year="2025", month="05")
print(f"\nReports for {calendar.year}-{calendar.month}: {len(calendar.reports)}")
for report in calendar.reports[:3]:
print(f" {report.title} — {report.url}")
# 4. Retrieve Cropland Data Layer download links
cdl = client.croplanddatalayers.get()
print(f"\nCDL datasets available: {len(cdl.cdl_resources)}")
for resource in cdl.cdl_resources[:3]:
print(f" {resource.title} — {resource.url}")
# 5. Handle a not-found error gracefully
try:
client.parameterdiscoveries.discover(target_param="nonexistent_param")
except ParameterNotFound as exc:
print(f"\nParameter not found: {exc.target_param}")
print("\nExercised: discover params / publications calendar / CDL links / error handling")
Discover valid parameter values for building QuickStats queries using the keyless internal web API. Returns all accepted values for a target parameter, optionally filtered by sector. Use to enumerate sectors, commodity groups, commodities, states, statistical categories, and aggregation levels available in the QuickStats database.
| Param | Type | Description |
|---|---|---|
| sector_desc | string | Filter values by sector. |
| target_param | string | The parameter to discover values for (e.g., sector_desc, group_desc, commodity_desc, state_alpha, statisticcat_desc, agg_level_desc). |
{
"type": "object",
"fields": {
"values": "array of objects with 'value' and 'label' string fields",
"parameter": "string, the target parameter that was queried"
}
}About the USDA API
QuickStats Parameter Discovery
The quickstats_discover_params endpoint returns valid values for any QuickStats query parameter, such as sector_desc, group_desc, commodity_desc, state_alpha, or statisticcat_desc. Each response includes a values array of objects with value and label fields, plus a parameter string confirming which field was queried. You can narrow results by passing a sector_desc filter — accepted values are CROPS, ANIMALS & PRODUCTS, DEMOGRAPHICS, ECONOMICS, and ENVIRONMENTAL. This makes it straightforward to enumerate exactly which commodity names, state codes, or statistic categories exist before constructing a downstream QuickStats query.
Publications Calendar
The get_publications_calendar endpoint returns scheduled NASS report releases for a given month and year. Pass year in YYYY format and month in zero-padded MM format. The response includes a reports array where each object contains a title, a url linking to the calendar landing page, and a params field. This is useful for tracking when crop production estimates, livestock inventories, or census releases are scheduled to publish.
Cropland Data Layer Downloads
The get_cropland_data_layer_links endpoint requires no inputs and returns cdl_resources: an array of objects with title (a description that includes file size) and url (a direct download link) fields. Resources cover national CDLs at both 10m and 30m resolution, cultivated layers, frequency layers, and confidence layers from 2008 to the present in GeoTIFF/ZIP format. These files are suitable for GIS workflows, land-use analysis, and agricultural mapping applications.
The USDA API is a managed, monitored endpoint for nass.usda.gov — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when nass.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 nass.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?+
- Enumerate all valid commodity names in the CROPS sector before building a QuickStats data pull
- Monitor the NASS publications calendar to trigger alerts when new crop production reports are scheduled
- Download Cropland Data Layer GeoTIFFs for multi-year land-use change analysis
- Build a state-level agricultural dashboard by iterating over all valid
state_alphavalues returned by parameter discovery - Identify which statistic categories (e.g., AREA HARVESTED, YIELD) are available for a given commodity
- Automate ingestion of annual CDL confidence layers for validating crop classification models
- Track upcoming NASS livestock inventory and farm economics report dates for research scheduling
| 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 NASS have an official developer API?+
What does `quickstats_discover_params` return when I pass a `sector_desc` filter?+
values array scoped to that sector, where each entry has a value string (the raw parameter value) and a label string. The parameter field in the response confirms which QuickStats field was queried. For example, filtering by sector_desc=CROPS and target_param=commodity_desc returns only crop commodity names.Does the API return the actual statistical data from QuickStats — yields, production volumes, prices?+
How current are the Cropland Data Layer links returned by `get_cropland_data_layer_links`?+
title field includes file size, which can help distinguish annual updates from archived layers.Can I filter the publications calendar by report type or crop sector?+
get_publications_calendar endpoint accepts only year and month parameters; filtering by report type or sector is not currently supported. Each report object includes a title and url field that can be used for client-side filtering. You can fork the API on Parse and revise it to add category-based filtering if the calendar source exposes that structure.