AOI Query

10 tokens per request

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 the complete GeoJSON geometry of each feature (whole field/section boundaries, dissolved across map tile boundaries server-side), not geometry clipped to the AOI. Default: false. The camelCase spelling includeGeometry is also accepted. 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.
parcels	polygon	Property parcels intersecting the AOI, with ownership and assessment attributes where available, intersection acreage, and percent coverage. Feature id is the parcel robust_id. Capped at 1,000 parcels per query (a warning is included when truncated). 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.
states	polygon	State boundaries intersecting the AOI. Maximum AOI: 5,000 acres.
plss	polygon	Hierarchical PLSS 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. Requesting a layer name that is not listed above returns a 400 error listing the invalid layers.

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. Each real-world feature (field, section, township) returns exactly one row, even when it spans multiple map tiles internally. Geometry is omitted by default for faster responses; request options.include_geometry: true when you need the complete feature boundaries for display or re-querying.

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. Ids are stable per dataset version: the same feature keeps the same id until the underlying dataset is rebuilt (announced in the changelog).
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.feature_acres	number \| null	Total acreage of the whole feature, including any part outside the AOI. For CLU fields this comes from the authoritative source acreage (calcacres).
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	Complete Polygon or MultiPolygon for the whole feature when options.include_geometry is true (dissolved across tile boundaries server-side; not clipped to the AOI). CDL crop summary features use null.
geometry_complete	boolean	Present only when geometry is included. True when the returned geometry represents the entire real-world feature; false in the rare case the feature could not be fully reconstructed.

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.

Geometry precision: returned boundaries are reconstructed from the tiled dataset (zoom 14–15, quantized and simplified at build time). They are suitable for rendering, PDFs, and acreage/statistics work within roughly 1–2% tolerance, but they are not survey-grade source coordinates.

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"]
  }
}