# Nassgeodata Gmu — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Access detailed USDA crop data including acreage statistics, satellite imagery, and crop classifications for any location across the United States. Compare agricultural patterns year-over-year, download raster data files, or retrieve specific crop information at the point level to analyze farming trends and land use.

**Category:** Government & Public Data | **Website:** [nassgeodata.gmu.edu/](https://nassgeodata.gmu.edu/) | **Docs:** [parse.bot/marketplace/7901e7bd-5737-47ec-9ea2-bba3c21686dc/nassgeodata-gmu-edu-api](https://parse.bot/marketplace/7901e7bd-5737-47ec-9ea2-bba3c21686dc/nassgeodata-gmu-edu-api)

Pay-per-use API proxy. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-nassgeodata-gmu-edu-api-7901e7bd/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### extract_cdl_by_values

Extract specific crop categories from an existing CDL GeoTIFF file. Accepts a GeoTIFF URL and a set of numeric crop category codes, and returns a URL to a new GeoTIFF containing only the specified categories.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `file_url` | string | Yes | URL to the CDL GeoTIFF file to extract from (e.g. from get_cdl_file). |
| `values` | string | Yes | Comma-separated crop category values to extract (e.g. '1,5' for Corn and Soybeans). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-nassgeodata-gmu-edu-api-7901e7bd/extract_cdl_by_values \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"file_url":"<string>","values":"<string>"}'
```

### get_cdl_file

Retrieve a URL to the CDL GeoTIFF file for a given year and FIPS area. The returned URL can be passed to get_cdl_image for rendering or extract_cdl_by_values for filtering.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `fips` | string | Yes | FIPS code for county or state area (e.g. '19001'). |
| `year` | string | Yes | Year of CDL data (e.g. '2021'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-nassgeodata-gmu-edu-api-7901e7bd/get_cdl_file \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fips":"<string>","year":"<string>"}'
```

### get_cdl_image

Convert a CDL GeoTIFF file URL into a rendered image (PNG or KML). Accepts a GeoTIFF URL (typically from get_cdl_file) and returns one or more rendered image URLs.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `files` | string | Yes | URL to a CDL GeoTIFF file (e.g. from get_cdl_file). |
| `format` | string | No | Output image format. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-nassgeodata-gmu-edu-api-7901e7bd/get_cdl_image \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"files":"<string>","format":"<string>"}'
```

### get_cdl_image_timeseries

Retrieve rendered CDL image URLs for a range of years for a given FIPS area. Each year produces a GeoTIFF which is then converted to the requested image format. Returns an array with per-year image URLs.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `end_year` | integer | Yes | End year of range (e.g. 2021). |
| `fips` | string | Yes | FIPS code for county or state area (e.g. '19001'). |
| `format` | string | No | Output image format. |
| `start_year` | integer | Yes | Start year of range (e.g. 2020). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-nassgeodata-gmu-edu-api-7901e7bd/get_cdl_image_timeseries \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"end_year":"<integer>","fips":"<string>","format":"<string>","start_year":"<integer>"}'
```

### get_cdl_pdf

Generate a PDF map of CDL data for a given year and FIPS area. Returns a URL to the generated PDF file.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `fips` | string | Yes | FIPS code for county or state area (e.g. '19001'). |
| `papersize` | string | No | Paper size. |
| `title` | string | No | Title for the PDF map. |
| `year` | string | Yes | Year of CDL data (e.g. '2021'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-nassgeodata-gmu-edu-api-7901e7bd/get_cdl_pdf \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fips":"<string>","papersize":"<string>","title":"<string>","year":"<string>"}'
```

### get_cdl_stat

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.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `fips` | string | Yes | FIPS code for county or state area (e.g. '19001' for Adair County, Iowa). |
| `format` | string | No | Output format. |
| `year` | string | Yes | Year of CDL data (e.g. '2021'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-nassgeodata-gmu-edu-api-7901e7bd/get_cdl_stat \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fips":"<string>","format":"<string>","year":"<string>"}'
```

### get_cdl_stat_timeseries

Retrieve cropland statistics for a range of years for a given FIPS area. Makes one request per year in the range and returns an array of per-year crop statistics. Each year's data includes all crop categories with acreage and pixel counts.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `end_year` | integer | Yes | End year of range (e.g. 2021). |
| `fips` | string | Yes | FIPS code for county or state area (e.g. '19001'). |
| `start_year` | integer | Yes | Start year of range (e.g. 2020). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-nassgeodata-gmu-edu-api-7901e7bd/get_cdl_stat_timeseries \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"end_year":"<integer>","fips":"<string>","start_year":"<integer>"}'
```

### get_cdl_value

Retrieve the CDL crop category value at a specific geographic point for a given year. Coordinates must be in the USA Contiguous Albers Equal Area (USGS) projection. Returns the category code, name, color, and the queried coordinates.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `x` | string | Yes | X coordinate in Albers Equal Area projection. |
| `y` | string | Yes | Y coordinate in Albers Equal Area projection. |
| `year` | string | Yes | Year of CDL data (e.g. '2021'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-nassgeodata-gmu-edu-api-7901e7bd/get_cdl_value \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"x":"<string>","y":"<string>","year":"<string>"}'
```