If you found a real bug, an outdated source, or a missing crop, please open an issue on GitHub. The catalog improves through specific corrections, not abstract feedback.
CropGraph is a planting calendar API for developers. Pass a coordinate and you get hardiness zone, climate type, frost dates, what to plant right now, and how crops relate to each other through companion and antagonist relationships.
The pitch in one sentence: zone alone is not enough to tell you when to plant. Two gardens 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.
Per crop, the API returns:
For a coordinate, the API also returns zone, sub-zone, climate type, frost dates, season length, and the source the zone was resolved from (PRISM 2023 nearest match, with distance in km).
The catalog is curated from public-domain and openly licensed sources:
Every crop record carries its source citation. If a relationship is unsourced, it does not ship.
The frost dates come from the PRISM 2023 zone map at nearest-coordinate resolution. The planting windows are anchored to those frost dates using sowing rules from the extension publications above. Most cases land within a week of what a local extension office would tell you.
Where CropGraph is more accurate than zone-only tools: it accounts for climate type, so maritime 8b (cool, slow soil warm-up) does not get the same calendar as continental 8b (faster soil warm-up, shorter spring transition). 120 crops carry climate-specific modifiers across all 6 climate types.
Where it can be less accurate than local knowledge: microclimates inside a single zone, unusual urban heat islands, and elevation effects below the PRISM grid resolution. If you build on top of the API and your users garden in those edge cases, treat the response as a starting point, not gospel.
Six climate types are modeled: maritime, mediterranean, continental, humid subtropical, arid, and semi arid. They are derived from coordinate plus PRISM zone data plus Köppen lookup tables.
A climate modifier on a crop adjusts that crop's sowing windows, soil-temperature requirement, or recommended action for a given climate type. Tomato in maritime 8b sows in May. Tomato in humid subtropical 8b sows in March. Same zone, different calendar.
If you want to override the detected climate (useful for testing or for users in unusual microclimates), pass ?climate=maritime to the planting endpoint.
The companion graph has 605 directed edges. Each edge has a mechanism (why the relationship exists) and a strength (how confident the source is). Mechanisms include pest repellent, nitrogen fixation, shade, ground cover, attractant for beneficials, allelopathy, structural support (Three Sisters corn-bean), pollinator attraction, and resource competition. Coverage includes fruit-tree guilds (apple, cherry, peach, pear, plum, fig, persimmon), cover-crop succession into cash crops, and cultivar-level brassica/nightshade family disease antagonism.
Antagonists are edges with type antagonist: pairs that should not share a bed because they compete for the same nutrients, attract the same pests, or actively suppress each other.
The /api/plan endpoint runs the graph against a bed: pass a list of crops, get every pairwise relationship deduplicated, plus warnings when one crop is antagonist to too many neighbors.
Every crop in the calendar is assigned to one of 12 botanical rotation families: nightshades (Solanaceae), brassicas (Brassicaceae), cucurbits (Cucurbitaceae), alliums (Amaryllidaceae), legumes (Fabaceae), umbellifers (Apiaceae), grasses (Poaceae), beets/spinach/amaranth (Amaranthaceae), lettuce/composites (Asteraceae), mints (Lamiaceae), okra/mallows (Malvaceae), and a miscellaneous catch-all for perennial fruit, nuts, asparagus, rhubarb, and ornamental flowers.
Each family carries a recommended year-gap before replanting (3 years for nightshades, 2 for brassicas/cucurbits/alliums/umbellifers/composites/amaranthaceae/malvaceae, 1 for grasses), a follow-with list (what to plant after this family), and a never-follow list (what should not follow). Rules are sourced from USDA Cooperative Extension, SARE, and Rodale.
The same rotation data ships on every surface: REST at GET /api/rotation/:slug and GET /api/rotation-check?sequence=…, the MCP get_rotation_advice and check_rotation_sequence tools, the CLI cropgraph rotation and cropgraph rotation-check subcommands, and the npm helpers getRotationAdvice / checkRotationSequence.
A succession chain is a time-sequenced planting schedule that turns a single bed into a continuous-harvest run across the season. The fixture has 33 chains across greens, roots, legumes, brassicas, cucurbits, herbs, cut flowers, and cover-crop relays. Each chain has an ordered list of phases. Each phase carries a crop slug, a sow method (direct_sow / transplant / start_indoors), an interval (every N weeks, or null for a single planting), a window expressed in days relative to the typical last spring frost, optional per-climate notes, and a gardener-facing prose note.
For a frost-relative view, ask for the chain by crop. For concrete ISO dates, supply a USDA zone or coordinates so the windows resolve against the zone's frost-date table. The same data ships on every surface: REST at GET /api/succession/:slug (frost-relative) and GET /api/succession-plan?crop=&lat=&lng= (dated), the MCP get_succession_chain and get_succession_plan tools, the CLI cropgraph succession <crop> command, and the npm helpers getSuccessionChain / getSuccessionPlan.
Sources include Johnny's Selected Seeds succession publications, Cornell Cooperative Extension small-farm planting calendars, UF/IFAS, UC ANR, the SARE Cover Crops field guide, and Eliot Coleman's succession tables.
158 crop-to-pest associations covering the most common backyard problems. Each entry has the crop slug, a pest or disease slug (e.g. tomato-hornworm, late-blight, cabbage-worm, squash-vine-borer), a type flag (pest or disease), a severity grade, diagnostic symptoms written for a gardener with a hand lens, an ordered list of organic management options, prevention practices, regions of significance, and a citation.
Management is intentionally restricted to OMRI-listed materials, biocontrols, and physical/cultural practices. Conventional synthetic pesticides are out of scope for this fixture.
The same data ships on every surface: REST at GET /api/pests/:slug (per-crop list) and GET /api/pest/:slug (per-pest detail across affected crops), the MCP get_crop_pests and get_pest_detail tools, the CLI cropgraph pests <crop> and cropgraph pest-detail <pest> commands, and the npm helpers getPestsByCrop, getPestDetail, getOrganicManagement, getCropsAffected, and searchPests.
Sources include Cornell Cooperative Extension, UC IPM Online, UF/IFAS Extension, Penn State Extension, OSU Extension, WSU Extension, Texas A&M AgriLife Extension, Rodale Encyclopedia of Organic Gardening, and USDA-ARS pest profiles.
Yes, through GET /api/soil?lat=&lng=. The endpoint resolves coordinates against the USDA NRCS Soil Survey Geographic Database (SSURGO), returns the dominant soil component for the map unit, and reports the soil series name, drainage class, surface texture, pH range across the profile, organic-matter level at the surface horizon, and rooting depth. A recommendations array cross-references those traits with crop preferences in the catalog (acid-loving crops for low pH, deep taproots for deep profiles, raised beds for poorly-drained soils, and so on).
SSURGO covers the United States and its territories. Points outside US coverage, or over open water, return a 404 with a clear message. The endpoint is cached for one week because SSURGO is static.
Why is this the only endpoint that calls an upstream service? Because SSURGO is too large to bundle into the npm package and changes too slowly to mirror locally with confidence. The hosted API absorbs the upstream call and the caching so callers do not have to. @cropgraph/core intentionally does not ship soil helpers; this is the first capability where the hosted API is genuinely more powerful than the npm package.
Source: USDA Natural Resources Conservation Service, Soil Data Access (SDA REST). Every response carries the citation in the source field.
/api/garden-plan return?Everything CropGraph knows about a coordinate plus a crop list, in one call. Pass lat, lng, and a comma-separated crops list and the endpoint traverses the entire knowledge graph at that location.
The response has three top-level sections. Location carries the USDA hardiness zone, the climate type, the frost-date pair (last spring, first fall), the frost-free season length, and the USDA SSURGO soil profile (series, drainage, texture, pH range, organic matter, recommendations) when the coordinate is in US coverage. Crops is an array, one entry per requested slug, each with the climate-aware planting window and action (start_indoors, direct_sow, transplant, plant_now), the GDD-based harvest prediction (earliest and latest dates, accumulated heat units, confidence band, base temperature), a succession-chain summary, rotation family and follow-with families, the top three pests sorted by severity with the leading organic management option, and crop-specific soil notes derived from the SSURGO profile. Bed analysis deduplicates every pairwise companion and antagonist edge across the requested crops, surfaces antagonist-hub warnings, and (optionally, when previous_crops is supplied) flags rotation conflicts against the prior planting sequence.
Optional parameters: year (default current year), climate (override the auto-detected climate type), include_soil=false (skip the SSURGO upstream call), and previous_crops (comma-separated CSV of last year's bed). Unknown crop slugs are returned in an unknownCrops array; the rest of the plan continues. Soil outages also degrade gracefully: soil becomes null with a soilError string, and the rest of the response is unaffected.
This is the endpoint no other agricultural API can build, because no other API has the six graph dimensions in one place. Garden-app developers make one call and get the complete plan.
Moderate confidence by default, high confidence when you supply daily temperatures.
CropGraph ships 65 literature-grounded growing-degree-day models covering the major vegetables, fruits, grains, and herbs. Base temperatures and heat-unit ranges come from Purdue, Cornell, UC Davis, USDA-ARS, OSU, and WSU Extension publications. The daily GDD formula is the standard one: max(0, (high + low) / 2 - baseTemp). When you do not supply daily temperatures, the /api/gdd and /api/garden-plan endpoints walk NOAA Climate Normals 1991-2020 month-by-month for the hardiness zone and climate type at the coordinate. That is 720 zone-x-climate-x-month entries derived from reference cities (Seattle for maritime, Sacramento for mediterranean, Chicago for continental, Atlanta for humid subtropical, Phoenix for arid, Denver for semi-arid) and scaled by zone. Absolute monthly values may differ by a few degrees from any single station, but the seasonal heat-accumulation pattern is representative.
The response carries a confidence field: high when manual avgDailyHigh and avgDailyLow were supplied (typically by a caller with a live weather feed), moderate when derived from Climate Normals, and low when the season has insufficient heat budget for the crop to reach its minimum maturity threshold within 365 days. The response also includes monthly accumulation so callers can see exactly where the heat units came from. Treat the predictions as planning guides; cultivars within the same crop can shift maturity by 30 to 60 GDD-percent, and microclimates matter.
Yes. 1,000 requests per month, rate limited to 60 per minute per IP. No API key required. No signup. No credit card. Responses include rate-limit headers so your client can back off gracefully.
Eventually, when there is real demand and the cost of serving free traffic stops being trivial. The current shape: 1,000 requests per month free forever, with paid tiers above that for production apps. Paid tiers will be priced like a developer tool, not like enterprise software.
If you are building something that will need higher throughput before paid tiers exist, get in touch through GitHub.
Yes. @cropgraph/mcp is on npm and registered on the official MCP Registry as io.github.Cropgraph/cropgraph. It 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, and get_pest_detail.
Run it with no install: npx @cropgraph/mcp. For Claude Desktop, add it to claude_desktop_config.json:
{ "mcpServers": { "cropgraph": { "command": "npx", "args": ["@cropgraph/mcp"] } } }
The 5,006-crop catalog and 605-edge companion graph ship inside the package, so the server works without network access.
Yes. cropgraph is on npm. Install globally with npm install -g cropgraph, or run any subcommand through npx cropgraph. Twelve subcommands mirror the MCP tools: zone, planting, crop, search, companions, check, plan, rotation, rotation-check, succession, pests, and pest-detail.
A few examples:
cropgraph zone --lat 48.118 --lng -123.43cropgraph planting --lat 48.118 --lng -123.43cropgraph companions tomatocropgraph plan tomato basil marigold carrotcropgraph succession lettuce --zone 8b --climate maritimecropgraph pests tomatoThe data ships in the package, so the CLI runs offline.
Yes. @cropgraph/core is the typed library that the API, the MCP server, and the CLI all depend on. Install it with npm install @cropgraph/core and you get every crop, every companion edge, and every zone lookup as plain TypeScript functions. No HTTP calls, no API key, no rate limit. The catalog ships inside the package.
Use the hosted API when you want a free service you can call from any language. Use @cropgraph/core when you want the data in-process: server-side rendering, offline tools, CI checks, generated content. The data is identical.
Those APIs are taxonomic plant databases. They tell you what a plant is. CropGraph tells you what to do with it, at your coordinate, on this date.
Specifically: CropGraph has frost-anchored sowing windows, climate-aware modifiers, days to harvest with expected harvest dates, companion and antagonist relationships with cited mechanisms, and a planning endpoint that operates on bed compositions. Those are agronomic capabilities, not taxonomic ones.
Use a taxonomic API to look up Solanum lycopersicum and get its family. Use CropGraph to know whether to direct-sow it on Tuesday.
Andrew Christison, on the Olympic Peninsula in Washington state. Built because the existing crop databases were either trapped behind enterprise contracts, frozen in a single zone, or limited to taxonomic data. The structured-data layer for gardening apps did not exist, so it had to.
Open an issue on GitHub. Include the crop slug, the field that is wrong, what the correct value should be, and a source citation. Issues with a verifiable source land in the next data release.
The catalog is curated, not crowdsourced. Specific corrections with sources are welcome. Vague complaints about a crop being "off" are harder to act on.
Still curious? The full API reference lives at /docs.