CDL Tiles

3 tokens per tile

Raster PNG tiles for the USDA Cropland Data Layer (CDL). Each pixel encodes a crop type code at 30-meter resolution, enabling crop identification and acreage analysis across the contiguous United States.

Tile Endpoint

GEThttps://api.landmapmagic.com/v1/tiles/cdl/{z}/{x}/{y}.png

Returns a grayscale PNG tile where each pixel value represents a crop type code. Zoom range: 0 – 15.

URL Parameters

Parameters

Name	Type	Description
z*	number	Zoom level (0-15).
x*	number	Tile X coordinate.
y*	number	Tile Y coordinate.
key*	string	Your API key.
year	number	CDL year (2019-2025). Defaults to 2025.

Code Examples

curl

# Fetch CDL tile for 2024 (default year)
curl "https://api.landmapmagic.com/v1/tiles/cdl/14/4215/6082.png?key=YOUR_API_KEY" \
  --output tile.png

# Fetch CDL tile for a specific year
curl "https://api.landmapmagic.com/v1/tiles/cdl/14/4215/6082.png?key=YOUR_API_KEY&year=2022" \
  --output tile_2022.png

JavaScript

// Fetch CDL tile as an image
const year = 2024;
const response = await fetch(
  `https://api.landmapmagic.com/v1/tiles/cdl/14/4215/6082.png?key=YOUR_API_KEY&year=${year}`
);
const blob = await response.blob();
const url = URL.createObjectURL(blob);

// Decode pixel values to read crop codes
const img = new Image();
img.src = url;
img.onload = () => {
  const canvas = document.createElement("canvas");
  canvas.width = img.width;
  canvas.height = img.height;
  const ctx = canvas.getContext("2d");
  ctx.drawImage(img, 0, 0);
  const pixel = ctx.getImageData(128, 128, 1, 1).data;
  console.log("Crop code at center:", pixel[0]); // grayscale value = crop code
};

Python

import requests
from io import BytesIO
from PIL import Image
import numpy as np

response = requests.get(
    "https://api.landmapmagic.com/v1/tiles/cdl/14/4215/6082.png",
    params={"key": "YOUR_API_KEY", "year": 2024}
)

img = Image.open(BytesIO(response.content))
pixels = np.array(img)
unique, counts = np.unique(pixels, return_counts=True)
for code, count in zip(unique, counts):
    print(f"Crop code {code}: {count} pixels")

Response

Response Headers

HTTP/1.1 200 OK
Content-Type: image/png
Cache-Control: public, max-age=86400

The response body is a 256x256 grayscale PNG image. Each pixel value (0-255) corresponds to a USDA NASS crop code. Use the colormap endpoint to map codes to colors and labels.

TileJSON Endpoint

GEThttps://api.landmapmagic.com/v1/tiles/cdl/tiles.json

Returns a TileJSON specification document describing the CDL tile layer, including bounds, zoom levels, and tile URL template.

curl

curl "https://api.landmapmagic.com/v1/tiles/cdl/tiles.json?key=YOUR_API_KEY"

JavaScript

const response = await fetch(
  "https://api.landmapmagic.com/v1/tiles/cdl/tiles.json?key=YOUR_API_KEY"
);
const tileJson = await response.json();
console.log("Tile URL template:", tileJson.tiles[0]);
console.log("Zoom range:", tileJson.minzoom, "-", tileJson.maxzoom);

Python

import requests

response = requests.get(
    "https://api.landmapmagic.com/v1/tiles/cdl/tiles.json",
    params={"key": "YOUR_API_KEY"}
)
tile_json = response.json()
print(f"Tile URL: {tile_json['tiles'][0]}")
print(f"Zoom: {tile_json['minzoom']}-{tile_json['maxzoom']}")

Example Response

{
  "tilejson": "3.0.0",
  "name": "CDL",
  "description": "USDA Cropland Data Layer",
  "tiles": [
    "https://api.landmapmagic.com/v1/tiles/cdl/{z}/{x}/{y}.png?key=YOUR_API_KEY"
  ],
  "minzoom": 0,
  "maxzoom": 15,
  "bounds": [-125.0, 24.0, -66.0, 50.0]
}

Colormap Endpoint

GEThttps://api.landmapmagic.com/v1/tiles/cdl/colormap.json

Returns a JSON mapping of crop codes to display colors and human-readable crop names. Use this to render colored maps and build legends.

curl

curl "https://api.landmapmagic.com/v1/tiles/cdl/colormap.json?key=YOUR_API_KEY"

JavaScript

const response = await fetch(
  "https://api.landmapmagic.com/v1/tiles/cdl/colormap.json?key=YOUR_API_KEY"
);
const colormap = await response.json();
// Look up crop code 1 (Corn)
console.log(colormap["1"]); // { color: [255, 211, 0], name: "Corn" }

Python

import requests

response = requests.get(
    "https://api.landmapmagic.com/v1/tiles/cdl/colormap.json",
    params={"key": "YOUR_API_KEY"}
)
colormap = response.json()
# Look up crop code 1 (Corn)
print(colormap["1"])  # {"color": [255, 211, 0], "name": "Corn"}

Example Response

{
  "1":   { "color": [255, 211, 0],   "name": "Corn" },
  "5":   { "color": [38, 115, 0],    "name": "Soybeans" },
  "24":  { "color": [166, 112, 0],   "name": "Winter Wheat" },
  "36":  { "color": [255, 167, 127], "name": "Alfalfa" },
  "61":  { "color": [191, 191, 119], "name": "Fallow/Idle Cropland" },
  "111": { "color": [75, 172, 198],  "name": "Open Water" },
  "121": { "color": [237, 0, 0],     "name": "Developed/Open Space" },
  "141": { "color": [109, 163, 64],  "name": "Deciduous Forest" },
  "176": { "color": [218, 217, 61],  "name": "Grass/Pasture" },
  "...": "..."
}

Common Crop Codes

Frequently Used Crop Codes

Attribute	Type	Description
1	Corn	Field corn (grain and silage). The most widely planted US crop.
5	Soybeans	Soybeans for grain. Second most common row crop.
24	Winter Wheat	Wheat planted in fall and harvested in early summer.
36	Alfalfa	Alfalfa hay and haylage, a perennial forage crop.
176	Grass/Pasture	Grassland and pastureland used for grazing or hay.
61	Fallow/Idle	Fallow or idle cropland not planted in the survey year.
111	Open Water	Open water bodies including lakes, rivers, and reservoirs.
121	Developed	Developed/open space including low-density residential and parks.
141	Forest	Deciduous forest cover.

The full CDL classification includes over 100 crop and land cover codes. Use the colormap endpoint for the complete mapping. Pixel value 0 indicates no data or background.

Data Source

The Cropland Data Layer is produced annually by the USDA National Agricultural Statistics Service (NASS) using satellite imagery from Landsat and other sensors at 30-meter resolution.

Coverage: Contiguous United States (CONUS). Alaska and Hawaii are not included.
Resolution: 30 meters per pixel, resampled to web mercator tiles.
Temporal range:2019 – 2025. Specify the year with the year query parameter. Defaults to 2025.
Update frequency: Annual. New crop year data is typically available in January following the growing season.
Format: Grayscale PNG where each pixel value (0-255) is a NASS crop code.

CDL tiles are raster PNG images, not vector tiles. They cannot be styled or queried per-feature like MVT layers. To analyze crop types within a specific area, read the pixel values from the PNG and map them using the colormap endpoint. Each tile request costs 3 tokens.