Gmu APInassgeodata.gmu.edu ↗
Access USDA CDL crop statistics, GeoTIFF files, point lookups, and time-series data for any US county or state via FIPS code.
What is the Gmu API?
This API exposes 8 endpoints covering USDA Cropland Data Layer (CDL) data, including acreage statistics by crop category, point-level crop classification, GeoTIFF file downloads, and rendered map images. The get_cdl_stat endpoint returns per-crop acreage for any US county or state by FIPS code and year, while get_cdl_stat_timeseries delivers the same breakdown across a range of years in a single call.
curl -X GET 'https://api.parse.bot/scraper/d13254c8-9694-4bbc-b5c1-3e61ffff4d61/get_cdl_stat?fips=19001&year=2021&format=json' \ -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 nassgeodata-gmu-edu-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.
from parse_apis.usda_nass_cropscape_cdl_api import CropScape, OutputFormat, ImageFormat, PaperSize
client = CropScape()
# Look up the crop category at a specific coordinate
point = client.pointvalues.get(x="1795250", y="1895700", year="2021")
print(point.category, point.value, point.color)
# Get crop statistics for a county
area = client.area(fips="19001")
stat = area.stat(year="2021", format=OutputFormat.JSON)
print(stat.url)
for row in stat.data.rows:
print(row.category, row.acreage, row.count)
# Retrieve GeoTIFF and render it as PNG
cdl_file = area.file(year="2021")
image = cdl_file.render(format=ImageFormat.PNG)
for url in image.urls:
print(url)
# Extract specific crops from the GeoTIFF
extraction = cdl_file.extract(values="1,5")
print(extraction.url)
# Get multi-year statistics
for year_stat in area.stat_timeseries(start_year=2020, end_year=2021):
print(year_stat.year, year_stat.data.totalCount)
# Generate a PDF map
pdf = area.pdf(year="2021", title="Adair County Crops", papersize=PaperSize.LETTER)
print(pdf.url)
Retrieve cropland statistics (acreage by crop category) for a given year and FIPS area. When format is 'json', returns both the URL to the stats file and the parsed crop data including per-category acreage, pixel count, and color. When format is 'csv', returns only the URL. Each row in the data represents one crop or land-use category observed in the area.
| Param | Type | Description |
|---|---|---|
| fipsrequired | string | FIPS code for county or state area (e.g. '19001' for Adair County, Iowa). |
| yearrequired | string | Year of CDL data (e.g. '2021'). |
| format | string | Output format. |
{
"type": "object",
"fields": {
"url": "string, URL to the stats file",
"data": "object containing parsed crop statistics with rows array (present only when format is 'json')"
},
"sample": {
"data": {
"url": "https://nassgeodata.gmu.edu/webservice/nass_data_cache/byfips/CDL_2021_19001.json",
"data": {
"rows": [
{
"color": "#FFD400",
"count": 485421,
"value": 1,
"acreage": 107955,
"category": "Corn"
}
],
"success": true,
"totalCount": 31
}
},
"status": "success"
}
}About the Gmu API
Crop Statistics and Point Lookups
The get_cdl_stat endpoint accepts a FIPS code (e.g., 19001 for Adair County, Iowa) and a year, returning a url to the stats file and, when format is set to json, a parsed data object with per-crop acreage rows. For coordinate-level queries, get_cdl_value takes x and y parameters in the USA Contiguous Albers Equal Area (USGS) projection and returns the CDL category name, integer value (crop code), and a color hex string used for map rendering. Note that coordinates outside the contiguous US projection will not return meaningful results.
File Downloads and Image Rendering
get_cdl_file returns a url pointing to the GeoTIFF raster for a given FIPS area and year. That URL can be piped directly into get_cdl_image, which converts the GeoTIFF into a PNG or KML and returns an array of rendered image URLs. extract_cdl_by_values takes a comma-separated list of crop category codes (e.g., 1,5 for Corn and Soybeans) and a GeoTIFF URL, returning a filtered GeoTIFF URL containing only those crop types.
Time-Series and Map Generation
get_cdl_stat_timeseries and get_cdl_image_timeseries both accept fips, start_year, and end_year parameters and return an array of per-year objects — either data (crop statistics) or urls (rendered image URLs). This makes year-over-year comparison straightforward without batching individual requests. The get_cdl_pdf endpoint generates a printable PDF map for a FIPS area and year, with optional title and papersize (Letter or A4) parameters, returning a URL to the generated document.
The Gmu API is a managed, monitored endpoint for nassgeodata.gmu.edu — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when nassgeodata.gmu.edu 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 nassgeodata.gmu.edu 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?+
- Track year-over-year corn and soybean acreage shifts in Iowa counties using
get_cdl_stat_timeseries - Identify the crop type at a specific field location by querying
get_cdl_valuewith Albers Equal Area coordinates - Download county-level GeoTIFF rasters via
get_cdl_filefor ingestion into GIS workflows - Produce printable county crop maps as PDFs using
get_cdl_pdffor USDA reporting or extension publications - Filter a CDL raster to only wheat pixels using
extract_cdl_by_valuesfor targeted land-use analysis - Generate KML overlays of CDL data with
get_cdl_imagefor visualization in Google Earth or mapping tools - Build a multi-year animated crop map by iterating
get_cdl_image_timeseriesresults across a date range
| 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 provide an official developer API for CDL data?+
What does `get_cdl_value` return, and what coordinate system does it require?+
category name (e.g., 'Corn'), the integer CDL value code, a color hex string, and the echoed x/y coordinates. Inputs must be in the USA Contiguous Albers Equal Area (USGS) projection — standard WGS84 latitude/longitude will not produce correct results and needs to be reprojected before querying.Does the API support sub-county geometries or custom bounding boxes for statistics?+
How far back does CDL year coverage go?+
year string, but requests for years outside available coverage will return no data or an error from the upstream service. Checking USDA NASS documentation for state-specific availability is advisable before building time-series queries.Can I retrieve CDL data for territories outside the contiguous United States, such as Hawaii or Alaska?+
get_cdl_value applies only to that region. You can fork this API on Parse and revise it if USDA adds coverage for non-contiguous areas in the future.