AOI Query

Token-based on area queried

Query data layers within an area of interest (AOI). Submit a GeoJSON polygon to retrieve soil survey data (SSURGO), cropland data (CDL), CLU boundaries, PLSS sections, and more for the specified region.

POSThttps://api.landmapmagic.com/v1/data/aoi

Request Body

Parameters

Name	Type	Description
aoi*	GeoJSON Feature	A GeoJSON Feature object with a Polygon geometry defining the area of interest. Maximum area: 5,000 acres per layer.
layers*	string[]	Array of layer names to query within the AOI. See Supported Layers below.

Supported Layers

Layer Limits

Attribute	Type	Description
ssurgo	polygon	USDA SSURGO soil survey data. Returns soil map unit polygons with properties. Maximum AOI: 5,000 acres.
cdl:YYYY	raster	USDA Cropland Data Layer for a specific year (e.g. cdl:2023). Returns crop summary statistics. Maximum AOI: 5,000 acres.
clu	polygon	Common Land Unit (CLU) field boundaries within the AOI. Maximum AOI: 5,000 acres.
sections	polygon	PLSS section boundaries intersecting the AOI. Maximum AOI: 5,000 acres.
townships	polygon	PLSS township boundaries intersecting the AOI. Maximum AOI: 5,000 acres.
counties	polygon	County boundaries intersecting the AOI. Maximum AOI: 5,000 acres.

All layers have a maximum AOI size of 5,000 acres. Requests exceeding this limit will return a 400 error with the specific limit that was exceeded.

SSURGO Response

SSURGO queries return a GeoJSON FeatureCollection with soil map unit polygons clipped to your AOI. Each feature includes the following properties:

SSURGO Feature Properties

Attribute	Type	Description
muname	string	Map unit name (e.g. "Clarion loam, 2 to 5 percent slopes").
hydgrp	string	Hydrologic soil group (A, B, C, D, or dual classes like A/D). Indicates runoff potential.
drainagecl	string	Natural drainage class (e.g. "Well drained", "Poorly drained", "Somewhat poorly drained").
nccpi	number	National Commodity Crop Productivity Index. Range 0-1, higher values indicate greater crop productivity.
musym	string	Map unit symbol used in the soil survey (e.g. "138B").
MUKEY	string	Unique map unit key identifier in the SSURGO database.
farmlndcl	string	Farmland classification (e.g. "All areas are prime farmland", "Farmland of statewide importance").
slope_dominant	number	Dominant slope gradient in percent.
nccpi_corn	number	NCCPI sub-score for corn (0-1).
nccpi_soy	number	NCCPI sub-score for soybeans (0-1).
csr2_ia	number \| null	Iowa Corn Suitability Rating 2 (CSR2). Range 5-100, higher is more productive. Only populated for Iowa soils.
pi_mn	number \| null	Minnesota Crop Productivity Index (CPI). Range 0-100. Only populated for Minnesota soils.
pi_il	number \| null	Illinois Soil Productivity Index (Bulletin 811). Range 0-147. Only populated for Illinois soils.

State-specific productivity indices (csr2_ia, pi_mn, pi_il) are only populated for soils in their respective states. They will be null for soils outside those states.

CDL Response

CDL queries return a crop summary with acreage statistics for the queried area and year.

CDL Response Fields

Attribute	Type	Description
aoi_area.acres	number	Total area of the AOI in acres.
aoi_area.hectares	number	Total area of the AOI in hectares.
aoi_area.square_meters	number	Total area of the AOI in square meters.
year	number	The CDL year queried.
crop_summary.total_pixels	number	Total number of CDL raster pixels within the AOI.
crop_summary.total_acres	number	Total classified acreage within the AOI.
crop_summary.crops	array	Array of crop objects sorted by acreage descending.
crop_summary.crops[].code	number	USDA CDL crop code.
crop_summary.crops[].name	string	Crop name.
crop_summary.crops[].pixel_count	number	Number of pixels classified as this crop.
crop_summary.crops[].acres	number	Estimated acreage for this crop.
crop_summary.crops[].percent	number	Percentage of AOI area covered by this crop.
query_info.timestamp	string	ISO 8601 timestamp of the query.
query_info.processing_time_ms	number	Server-side processing time in milliseconds.
query_info.tiles_queried	number	Number of CDL raster tiles queried.
query_info.zoom_level	number	Zoom level used for raster sampling.

Common Crop Codes

Frequently Used CDL Crop Codes

Attribute	Type	Description
1	Corn	Field corn (grain and silage). The most common crop in the Midwest.
5	Soybeans	Soybeans. Often rotated with corn in Midwest farming operations.
24	Winter Wheat	Winter wheat. Planted in fall, harvested the following summer.
36	Alfalfa	Alfalfa hay. Perennial forage crop common in dairy regions.
176	Grass/Pasture	Grassland and managed pasture used for livestock grazing.
61	Fallow/Idle	Fallow or idle cropland. Land not planted during the survey year.

Code Examples

SSURGO Query

cURL

curl -X POST "https://api.landmapmagic.com/v1/data/aoi?key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "aoi": {
      "type": "Feature",
      "geometry": {
        "type": "Polygon",
        "coordinates": [[
          [-93.49, 42.02],
          [-93.48, 42.02],
          [-93.48, 42.03],
          [-93.49, 42.03],
          [-93.49, 42.02]
        ]]
      },
      "properties": {}
    },
    "layers": ["ssurgo"]
  }'

JavaScript

const aoi = {
  type: "Feature",
  geometry: {
    type: "Polygon",
    coordinates: [[
      [-93.49, 42.02],
      [-93.48, 42.02],
      [-93.48, 42.03],
      [-93.49, 42.03],
      [-93.49, 42.02],
    ]],
  },
  properties: {},
};

const response = await fetch(
  "https://api.landmapmagic.com/v1/data/aoi?key=YOUR_API_KEY",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      aoi,
      layers: ["ssurgo"],
    }),
  }
);
const data = await response.json();
data.results.ssurgo.features.forEach((f) => {
  const p = f.properties;
  console.log(p.muname, "NCCPI:", p.nccpi, "CSR2:", p.csr2_ia);
});

Python

import requests

aoi = {
    "type": "Feature",
    "geometry": {
        "type": "Polygon",
        "coordinates": [[
            [-93.49, 42.02],
            [-93.48, 42.02],
            [-93.48, 42.03],
            [-93.49, 42.03],
            [-93.49, 42.02],
        ]],
    },
    "properties": {},
}

response = requests.post(
    "https://api.landmapmagic.com/v1/data/aoi?key=YOUR_API_KEY",
    json={
        "aoi": aoi,
        "layers": ["ssurgo"],
    },
)
data = response.json()
for feature in data["results"]["ssurgo"]["features"]:
    props = feature["properties"]
    print(f"{props['muname']} — NCCPI: {props['nccpi']} CSR2: {props.get('csr2_ia')}")

CDL Crop Summary Query

cURL

curl -X POST "https://api.landmapmagic.com/v1/data/aoi?key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "aoi": {
      "type": "Feature",
      "geometry": {
        "type": "Polygon",
        "coordinates": [[
          [-93.50, 42.01],
          [-93.47, 42.01],
          [-93.47, 42.04],
          [-93.50, 42.04],
          [-93.50, 42.01]
        ]]
      },
      "properties": {}
    },
    "layers": ["cdl:2023"]
  }'

JavaScript

const aoi = {
  type: "Feature",
  geometry: {
    type: "Polygon",
    coordinates: [[
      [-93.50, 42.01],
      [-93.47, 42.01],
      [-93.47, 42.04],
      [-93.50, 42.04],
      [-93.50, 42.01],
    ]],
  },
  properties: {},
};

const response = await fetch(
  "https://api.landmapmagic.com/v1/data/aoi?key=YOUR_API_KEY",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      aoi,
      layers: ["cdl:2023"],
    }),
  }
);
const data = await response.json();
const summary = data.results["cdl:2023"].crop_summary;
console.log("Total acres:", summary.total_acres);
summary.crops.forEach((c) => {
  console.log(`${c.name}: ${c.acres} acres (${c.percent}%)`);
});

Python

import requests

aoi = {
    "type": "Feature",
    "geometry": {
        "type": "Polygon",
        "coordinates": [[
            [-93.50, 42.01],
            [-93.47, 42.01],
            [-93.47, 42.04],
            [-93.50, 42.04],
            [-93.50, 42.01],
        ]],
    },
    "properties": {},
}

response = requests.post(
    "https://api.landmapmagic.com/v1/data/aoi?key=YOUR_API_KEY",
    json={
        "aoi": aoi,
        "layers": ["cdl:2023"],
    },
)
data = response.json()
summary = data["results"]["cdl:2023"]["crop_summary"]
print(f"Total acres: {summary['total_acres']}")
for crop in summary["crops"]:
    print(f"{crop['name']}: {crop['acres']} acres ({crop['percent']}%)")

Response Examples

SSURGO Query Response

{
  "results": {
    "ssurgo": {
      "type": "FeatureCollection",
      "features": [
        {
          "type": "Feature",
          "geometry": {
            "type": "Polygon",
            "coordinates": [[
              [-93.49, 42.02],
              [-93.485, 42.02],
              [-93.485, 42.025],
              [-93.49, 42.025],
              [-93.49, 42.02]
            ]]
          },
          "properties": {
            "muname": "Clarion loam, 2 to 5 percent slopes",
            "hydgrp": "B",
            "drainagecl": "Well drained",
            "farmlndcl": "All areas are prime farmland",
            "nccpi": 0.87,
            "nccpi_corn": 0.85,
            "nccpi_soy": 0.87,
            "slope_dominant": 3,
            "musym": "138B",
            "MUKEY": "362547",
            "csr2_ia": 88,
            "pi_mn": null,
            "pi_il": null
          }
        },
        {
          "type": "Feature",
          "geometry": {
            "type": "Polygon",
            "coordinates": [[
              [-93.485, 42.02],
              [-93.48, 42.02],
              [-93.48, 42.028],
              [-93.485, 42.028],
              [-93.485, 42.02]
            ]]
          },
          "properties": {
            "muname": "Nicollet clay loam, 1 to 3 percent slopes",
            "hydgrp": "B",
            "drainagecl": "Somewhat poorly drained",
            "farmlndcl": "All areas are prime farmland",
            "nccpi": 0.91,
            "nccpi_corn": 0.88,
            "nccpi_soy": 0.91,
            "slope_dominant": 2,
            "musym": "507B",
            "MUKEY": "362612",
            "csr2_ia": 91,
            "pi_mn": null,
            "pi_il": null
          }
        },
        {
          "type": "Feature",
          "geometry": {
            "type": "Polygon",
            "coordinates": [[
              [-93.488, 42.025],
              [-93.482, 42.025],
              [-93.482, 42.03],
              [-93.488, 42.03],
              [-93.488, 42.025]
            ]]
          },
          "properties": {
            "muname": "Webster silty clay loam, 0 to 2 percent slopes",
            "hydgrp": "B/D",
            "drainagecl": "Poorly drained",
            "farmlndcl": "All areas are prime farmland",
            "nccpi": 0.82,
            "nccpi_corn": 0.79,
            "nccpi_soy": 0.82,
            "slope_dominant": 1,
            "musym": "850A",
            "MUKEY": "362701",
            "csr2_ia": 95,
            "pi_mn": null,
            "pi_il": null
          }
        }
      ]
    }
  }
}

CDL Query Response

{
  "results": {
    "cdl:2023": {
      "aoi_area": {
        "acres": 648.3,
        "hectares": 262.4,
        "square_meters": 2624210.5
      },
      "year": 2023,
      "crop_summary": {
        "total_pixels": 72481,
        "total_acres": 648.3,
        "crops": [
          {
            "code": 1,
            "name": "Corn",
            "pixel_count": 35280,
            "acres": 315.6,
            "percent": 48.7
          },
          {
            "code": 5,
            "name": "Soybeans",
            "pixel_count": 28120,
            "acres": 251.5,
            "percent": 38.8
          },
          {
            "code": 176,
            "name": "Grass/Pasture",
            "pixel_count": 5430,
            "acres": 48.6,
            "percent": 7.5
          },
          {
            "code": 36,
            "name": "Alfalfa",
            "pixel_count": 2105,
            "acres": 18.8,
            "percent": 2.9
          },
          {
            "code": 61,
            "name": "Fallow/Idle",
            "pixel_count": 1546,
            "acres": 13.8,
            "percent": 2.1
          }
        ]
      },
      "query_info": {
        "timestamp": "2025-06-15T14:32:07.123Z",
        "processing_time_ms": 342,
        "tiles_queried": 4,
        "zoom_level": 13
      }
    }
  }
}