# CropGraph

> The climate-aware planting calendar API. 5,006 curated crops across 14 categories with frost-anchored planting windows, 605 companion relationships, 12 rotation families, 33 succession planting chains, 158 pest/disease associations, 120 growing degree day models with NOAA Climate Normals harvest prediction, 6 climate types, USDA hardiness zone lookup, and SSURGO soil intelligence by coordinate. Free, no API key required.

## What is CropGraph

CropGraph is a structured-data platform for developers building gardening apps, seed-company planting calculators, and LLM agents that need agricultural data. It ships three surfaces over the same 5,006-crop catalog: a REST API, a Model Context Protocol server, and a CLI. Given a coordinate, all three return hardiness zone, climate type, frost dates, what to plant right now, and how crops relate to each other through companion and antagonist relationships. The REST API additionally returns USDA SSURGO soil profiles by coordinate.

Zone alone is not enough. Two coordinates in USDA zone 8b can have planting calendars that differ by six weeks because one is maritime and the other is humid subtropical. CropGraph models that with 6 climate types and 120 climate-specific crop modifiers.

The catalog is 5,006 curated crops across 14 categories sourced from USDA Cooperative Extension publications (Cornell, WSU, UC ANR, UF / IFAS, OSU, Penn State, Texas A&M), USDA-ARS Three Sisters research, Xerces Society pollinator publications, Native Seeds/SEARCH heritage seed collections, breeder release records from Rutgers / Cornell NYSAES / WSU / USDA-ARS / James Hutton, and PRISM 2023 USDA Plant Hardiness Zone Map. Every entry includes days to harvest, sowing windows, growing context, minimum soil temperature, zone range, and source citation. Named cultivars across tomato, pepper, apple, grape, blueberry, raspberry, strawberry, pear, peach, plum, melon, watermelon, bean, pea, corn, squash, lettuce, carrot, onion, garlic.

## API Endpoints

Base URL: https://api.cropgraph.com

- GET /api/zone?lat=&lng= : USDA hardiness zone, climate type, frost dates, season length
- GET /api/planting?lat=&lng= : what to plant right now, climate-aware, enriched with companions
- GET /api/crop/{slug} : full crop detail with companions and antagonists
- GET /api/companions/{slug} : companions plus antagonists with cited mechanisms
- GET /api/check?a=&b= : directed relationship between two crops
- GET /api/plan?crops=a,b,c : bed compatibility report for a list of crops
- GET /api/crops?category=&zone= : filter and list crops
- GET /api/search?q= : fuzzy search across slug, common name, scientific name, aliases
- GET /api/rotation/{slug} : rotation family, year-gap, follow-with and never-follow families
- GET /api/rotation-check?sequence=a,b,c : validate a multi-year planting sequence
- GET /api/succession/{slug} : frost-anchored succession chain for a crop or chain slug
- GET /api/succession-plan?crop=&lat=&lng= : succession chain resolved to concrete ISO dates for a coordinate
- GET /api/pests/{slug} : pests and diseases affecting a crop, ranked by severity
- GET /api/pest/{slug} : full record for one pest or disease across every crop it affects
- GET /api/soil?lat=&lng= : USDA SSURGO soil profile (series, drainage, texture, pH, organic matter, recommendations) for a coordinate
- GET /api/garden-plan?lat=&lng=&crops=a,b,c : the complete garden plan for a coordinate. One call traverses every graph dimension: zone, climate, frost dates, soil profile, planting windows, GDD-based harvest prediction, succession, rotation, pests, and bed-level companion and antagonist analysis. Six dimensions, one request.
- GET /api/gdd?crop=&lat=&lng=&plant_date= : growing-degree-day harvest prediction. Returns earliest and latest harvest dates, monthly heat-unit accumulation, and the base-temperature model used. Falls back to NOAA Climate Normals when no live weather is supplied.

All endpoints return JSON. No API key. Rate limit: 60 requests per minute per IP. Free tier: 1,000 requests per month. The /api/soil and /api/garden-plan endpoints call USDA NRCS Soil Data Access upstream (cached one week per coordinate); every other endpoint is served from the in-process catalog.

## Example

curl "https://api.cropgraph.com/api/planting?lat=48.118&lng=-123.43"

Returns zone, climate type, frost dates, and a plantNow array of crops with sowing actions (direct_sow, transplant, indoor_start), windows, days to harvest, companions, and antagonists.

curl "https://api.cropgraph.com/api/soil?lat=48.118&lng=-123.43"

Returns the dominant SSURGO map unit for the coordinate: soil series, drainage class, surface texture, pH range, organic-matter level, rooting depth, and a recommendations array cross-referenced with crop preferences.

curl "https://api.cropgraph.com/api/garden-plan?lat=48.118&lng=-123.43&crops=tomato,basil,bush-bean,carrot,kale"

Returns the complete garden plan: location (zone, climate, frost dates, soil), per-crop planting window, GDD-based harvest prediction, succession chain summary, rotation family, top three pests with management notes, soil notes specific to the crop, plus bed-level companion and antagonist edges and any rotation conflicts against an optional previous_crops sequence. One call, six graph dimensions.

curl "https://api.cropgraph.com/api/gdd?crop=tomato&lat=48.118&lng=-123.43&plant_date=2026-05-15"

Returns the earliest and latest harvest dates for a planting, monthly GDD accumulation, the base-temperature model, and the confidence band.

## MCP server

Package: @cropgraph/mcp (npm). Registry ID: io.github.Cropgraph/cropgraph on the official MCP Registry at registry.modelcontextprotocol.io.

Install and run with no setup: npx @cropgraph/mcp

The server exposes fourteen tools, all backed by the same offline catalog: get_hardiness_zone, get_planting_plan, get_crop_details, search_plants, get_crops_for_zone, get_companions, check_companion_pair, plan_bed_compatibility, get_rotation_advice, check_rotation_sequence, get_succession_chain, get_succession_plan, get_crop_pests, get_pest_detail.

Claude Desktop config:

{
  "mcpServers": {
    "cropgraph": { "command": "npx", "args": ["@cropgraph/mcp"] }
  }
}

## CLI

Package: cropgraph (npm). Install globally with npm install -g cropgraph, or run any subcommand through npx cropgraph.

Subcommands: zone, planting, crop, search, companions, check, plan, rotation, rotation-check, succession, pests, pest-detail. Examples:

cropgraph zone --lat 48.118 --lng -123.43
cropgraph planting --lat 48.118 --lng -123.43
cropgraph companions tomato
cropgraph plan tomato basil marigold carrot
cropgraph rotation tomato
cropgraph rotation-check tomato bush-bean sweet-corn cabbage
cropgraph succession lettuce --zone 8b --climate maritime
cropgraph pests tomato
cropgraph pest-detail cabbage-worm

All data ships in the package, so the CLI works without network access.

## Data Sources

- USDA Cooperative Extension publications (Cornell CALS, WSU, UC ANR, UF / IFAS, OSU, Penn State, Texas A&M)
- USDA-ARS Three Sisters research
- Xerces Society pollinator publications
- PRISM 2023 USDA Plant Hardiness Zone Map
- USDA NRCS Soil Survey Geographic Database (SSURGO), via Soil Data Access (soil endpoint)
- Riotte, Carrots Love Tomatoes
- Cunningham, Great Garden Companions
- Rodale Encyclopedia

## Roadmap

Shipped: 17 REST endpoints (zone, planting, crop, companions, check, plan, crops, search, rotation, rotation-check, succession, succession-plan, pests, pest, soil, garden-plan, gdd), MCP server (14 tools, registered), CLI (12 subcommands), 5,006 crops, 605 relationships, 12 rotation families, 33 succession planting chains, 158 pest/disease associations, 120 growing degree day models with NOAA Climate Normals harvest prediction, 6 climate types, 26 USDA zones, SSURGO soil intelligence by coordinate.

Coming: 3,000+ crop expansion, live weather GDD overlay.

## Links

- Website: https://cropgraph.com
- API: https://api.cropgraph.com
- Documentation: https://cropgraph.com/docs
- FAQ: https://cropgraph.com/faq
- Privacy: https://cropgraph.com/privacy
- GitHub: https://github.com/Cropgraph/cropgraph-api

## Author

Andrew Christison, Port Angeles, Washington. Built because the structured-data layer for gardening apps did not exist.