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: 50,000 acres per query.
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: 1,000 acres.
clu	polygon	Common Land Unit (CLU) field boundaries within the AOI. Area limit varies by region.
sections	polygon	PLSS section boundaries intersecting the AOI. Area limit varies by region.
townships	polygon	PLSS township boundaries intersecting the AOI. Area limit varies by region.
counties	polygon	County boundaries intersecting the AOI. Area limit varies by region.

The maximum AOI size is 50,000 acres per query across all layers. Individual layers may have stricter limits: SSURGO is capped at 5,000 acres and CDL at 1,000 acres. Requests exceeding these limits 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.

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" \
  -H "Authorization: Bearer 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",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      aoi,
      layers: ["ssurgo"],
    }),
  }
);
const data = await response.json();
// data.results.ssurgo is a GeoJSON FeatureCollection
data.results.ssurgo.features.forEach((f) => {
  console.log(f.properties.muname, "NCCPI:", f.properties.nccpi);
});

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",
    headers={"Authorization": "Bearer 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']}")

CDL Crop Summary Query

cURL

curl -X POST "https://api.landmapmagic.com/v1/data/aoi" \
  -H "Authorization: Bearer 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",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer YOUR_API_KEY",
      "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",
    headers={"Authorization": "Bearer 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",
            "nccpi": 0.87,
            "musym": "138B",
            "MUKEY": "362547"
          }
        },
        {
          "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",
            "nccpi": 0.91,
            "musym": "507B",
            "MUKEY": "362612"
          }
        },
        {
          "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",
            "nccpi": 0.82,
            "musym": "850A",
            "MUKEY": "362701"
          }
        }
      ]
    }
  }
}

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

Loading documentation...