nassgeodata.gmu.edu 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.
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'
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. When format is 'csv', returns only the URL.
| 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: 'json' or 'csv'. |
{
"type": "object",
"fields": {
"url": "string, URL to the stats file",
"data": "object containing parsed crop statistics (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"
},
{
"color": "#267300",
"count": 505151,
"value": 5,
"acreage": 112342.9,
"category": "Soybeans"
}
],
"success": true,
"fileName": "D:/CDL/NASS_DATA_CACHE/byfips/CDL_2021_19001.tif",
"totalCount": 31
}
},
"status": "success"
}
}About the nassgeodata.gmu.edu 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.
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.
- 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 | 250 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.