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 in one consistent features[] response shape.

Try AOI query

Live demo against the production API. Pick a preset to fill the AOI and layer chips, or paste your own GeoJSON Feature with a Polygon geometry. Each layer caps the AOI at 5,000 acres.

POST https://api.landmapmagic.com/v1/data/aoi?key=YOUR_API_KEYShow body ▾

{
  "aoi": {
    "type": "Feature",
    "properties": {
      "name": "Ames small field"
    },
    "geometry": {
      "type": "Polygon",
      "coordinates": [
        [
          [
            -93.49,
            42.02
          ],
          [
            -93.48,
            42.02
          ],
          [
            -93.48,
            42.03
          ],
          [
            -93.49,
            42.03
          ],
          [
            -93.49,
            42.02
          ]
        ]
      ]
    }
  },
  "layers": [
    "ssurgo",
    "clu",
    "sections",
    "townships",
    "counties",
    "cdl:2025",
    "cdl:2024"
  ],
  "options": {
    "include_geometry": true
  }
}

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.
options.include_geometry	boolean	When true, vector layer features include GeoJSON geometry. Default: false. CDL crop summary features always use geometry: null because the API summarizes raster pixels rather than returning individual pixels.

Supported Layers

Layer Limits

Attribute	Type	Description
ssurgo	polygon	USDA SSURGO soil survey data. Returns one normalized soil map unit feature per MUKEY with acreage and percent coverage. Geometry is null unless options.include_geometry is true. Maximum AOI: 5,000 acres.
cdl:YYYY	raster_summary	USDA Cropland Data Layer for a specific year (e.g. cdl:2023). Returns one feature per crop class with acreage and percent coverage. 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.

Unified Response

All AOI layers now return through the same envelope: layers[layerName].features[]. Vector layers, SSURGO soil units, and CDL crop summaries all use id, name,kind, area, properties, andgeometry. Geometry is omitted by default for faster responses; request options.include_geometry: true when you need clipped polygons for display.

Top-Level Fields

Attribute	Type	Description
aoi.area	object	Area measurements for the submitted AOI.
layers	object	Object keyed by requested layer name, such as ssurgo, clu, or cdl:2023.
layers[layer].type	string	Layer result type. Vector and SSURGO layers return vector; CDL returns raster_summary.
layers[layer].feature_count	number	Number of normalized features returned for the layer.
layers[layer].features	array	Normalized feature rows for this layer.
summary	object	Overall layer count, total feature count, and processing time.

Feature Fields

Attribute	Type	Description
id	string	Stable identifier for the feature within its layer.
name	string	Human-readable feature name.
kind	string	Feature kind, such as field_boundary, soil_map_unit, plss_section, or crop.
area.intersection_acres	number \| null	Acres represented inside the AOI. For CDL, this is the crop acreage. For vectors, this is the intersected polygon acreage.
area.percent_of_aoi_in_feature	number \| null	Percent of the AOI represented by this feature or crop class.
properties	object	Layer-specific attributes. SSURGO keeps soil properties here; CDL keeps crop code, year, and pixel counts here.
geometry	GeoJSON geometry \| null	GeoJSON geometry for vector features when available. CDL crop summary features use null.

CDL does not return every raster pixel inside the AOI. It returns one normalized feature per crop class, with geometry: null and acreage/percent statistics in area.

SSURGO Properties

SSURGO features use the same normalized feature wrapper as every other AOI layer. Soil-specific attributes remain in each feature's properties object.

Common SSURGO 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").
csr2_ia	number \| null	Iowa Corn Suitability Rating 2 (CSR2). Only populated for Iowa soils.

CDL Crop Features

CDL crop summaries are represented as normalized features with kind: "crop". Each crop feature has no geometry, but uses the same area and properties fields as vector AOI features.

CDL Feature Properties

Attribute	Type	Description
properties.year	string	The CDL year queried.
properties.crop_code	number	USDA CDL crop code.
properties.crop_name	string	Crop name.
properties.pixel_count	number	Number of pixels classified as this crop.
area.intersection_acres	number	Estimated acreage for this crop.
area.percent_of_aoi_in_feature	number	Percentage of AOI area covered by this crop.
metadata.total_pixels	number	Total number of CDL raster pixels sampled for the layer.
metadata.tiles_queried	number	Number of CDL raster tiles queried.
metadata.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=lmm_live_4f7k...z9Qp" \
  -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"],
    "options": {
      "include_geometry": false
    }
  }'

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=lmm_live_4f7k...z9Qp",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      aoi,
      layers: ["ssurgo"],
      options: {
        include_geometry: false,
      },
    }),
  }
);
const data = await response.json();
data.layers.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=lmm_live_4f7k...z9Qp",
    json={
        "aoi": aoi,
        "layers": ["ssurgo"],
        "options": {
            "include_geometry": False,
        },
    },
)
data = response.json()
for feature in data["layers"]["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=lmm_live_4f7k...z9Qp" \
  -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=lmm_live_4f7k...z9Qp",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      aoi,
      layers: ["cdl:2023"],
    }),
  }
);
const data = await response.json();
const cropLayer = data.layers["cdl:2023"];
console.log("Total acres:", cropLayer.metadata.total_acres);
cropLayer.features.forEach((crop) => {
  console.log(
    `${crop.name}: ${crop.area.intersection_acres} acres (${crop.area.percent_of_aoi_in_feature}%)`
  );
});

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=lmm_live_4f7k...z9Qp",
    json={
        "aoi": aoi,
        "layers": ["cdl:2023"],
    },
)
data = response.json()
crop_layer = data["layers"]["cdl:2023"]
print(f"Total acres: {crop_layer['metadata']['total_acres']}")
for crop in crop_layer["features"]:
    print(
        f"{crop['name']}: {crop['area']['intersection_acres']} acres "
        f"({crop['area']['percent_of_aoi_in_feature']}%)"
    )

Response Examples

SSURGO Query Response

{
  "aoi": {
    "area": {
      "acres": 12.4,
      "hectares": 5.0,
      "square_meters": 50181.1,
      "square_kilometers": 0.05,
      "square_miles": 0.019
    }
  },
  "layers": {
    "ssurgo": {
      "type": "vector",
      "status": "ok",
      "feature_count": 2,
      "features": [
        {
          "id": "soil:362547",
          "name": "Clarion loam, 2 to 5 percent slopes",
          "kind": "soil_map_unit",
          "area": {
            "intersection_acres": 7.8,
            "feature_acres": null,
            "percent_of_feature_in_aoi": null,
            "percent_of_aoi_in_feature": 62.9
          },
          "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
          },
          "geometry": null
        },
        {
          "id": "soil:362612",
          "name": "Nicollet clay loam, 1 to 3 percent slopes",
          "kind": "soil_map_unit",
          "area": {
            "intersection_acres": 4.6,
            "feature_acres": null,
            "percent_of_feature_in_aoi": null,
            "percent_of_aoi_in_feature": 37.1
          },
          "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
          },
          "geometry": null
        }
      ]
    }
  },
  "summary": {
    "layers_queried": ["ssurgo"],
    "total_features_found": 2,
    "processing_time_ms": 287
  },
  "query": {
    "timestamp": "2026-05-03T23:22:00.000Z",
    "requested_layers": ["ssurgo"]
  }
}

CDL Query Response

{
  "aoi": {
    "area": {
      "acres": 648.3,
      "hectares": 262.4,
      "square_meters": 2624210.5,
      "square_kilometers": 2.624,
      "square_miles": 1.013
    }
  },
  "layers": {
    "cdl:2023": {
      "type": "raster_summary",
      "status": "ok",
      "feature_count": 3,
      "features": [
        {
          "id": "crop:2023:1",
          "name": "Corn",
          "kind": "crop",
          "area": {
            "intersection_acres": 315.6,
            "feature_acres": null,
            "percent_of_feature_in_aoi": null,
            "percent_of_aoi_in_feature": 48.7
          },
          "properties": {
            "year": "2023",
            "crop_code": 1,
            "crop_name": "Corn",
            "pixel_count": 35280,
            "total_pixels": 72481
          },
          "geometry": null
        },
        {
          "id": "crop:2023:5",
          "name": "Soybeans",
          "kind": "crop",
          "area": {
            "intersection_acres": 251.5,
            "feature_acres": null,
            "percent_of_feature_in_aoi": null,
            "percent_of_aoi_in_feature": 38.8
          },
          "properties": {
            "year": "2023",
            "crop_code": 5,
            "crop_name": "Soybeans",
            "pixel_count": 28120,
            "total_pixels": 72481
          },
          "geometry": null
        },
        {
          "id": "crop:2023:176",
          "name": "Grass/Pasture",
          "kind": "crop",
          "area": {
            "intersection_acres": 48.6,
            "feature_acres": null,
            "percent_of_feature_in_aoi": null,
            "percent_of_aoi_in_feature": 7.5
          },
          "properties": {
            "year": "2023",
            "crop_code": 176,
            "crop_name": "Grass/Pasture",
            "pixel_count": 5430,
            "total_pixels": 72481
          },
          "geometry": null
        }
      ],
      "metadata": {
        "year": "2023",
        "total_pixels": 72481,
        "total_acres": 648.3,
        "tiles_queried": 4,
        "zoom_level": 13
      }
    }
  },
  "summary": {
    "layers_queried": ["cdl:2023"],
    "total_features_found": 3,
    "processing_time_ms": 342
  },
  "query": {
    "timestamp": "2026-05-03T23:22:00.000Z",
    "requested_layers": ["cdl:2023"]
  }
}