CropGraph API.

USDA hardiness zone, climate type, frost dates, season length for a coordinate.

Example

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

{
  "coordinates": { "lat": 48.118, "lng": -123.43 },
  "zone": { "zone": "8b", "zoneNumber": 8, "subzone": "b", "minTempF": 15, "maxTempF": 20 },
  "frostDates": { "zone": "8b", "lastSpring": "04-15", "firstFall": "11-10", "seasonDays": 209 },
  "seasonDays": 209,
  "climateType": "maritime"
}

What to plant right now at a given coordinate. Returns the planting plan, each suggestion enriched with companions and antagonists.

Example

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

Full crop detail plus companions and antagonists. Slug is matched against crop slug, common name, scientific name, or alias. Returns 404 if no match.

Example

curl "https://api.cropgraph.com/api/crop/tomato"

{
  "crop": { "slug": "tomato", "commonName": "Tomato", "scientificName": "Solanum lycopersicum" },
  "companions": [
    { "crop": "tomato", "companion": "basil", "type": "beneficial", "mechanism": "pest_repellent", "strength": "strong" }
  ],
  "antagonists": [
    { "crop": "tomato", "companion": "fennel-herb", "type": "antagonist" }
  ]
}

Companions and antagonists for one crop, with cited mechanisms and strengths.

Example

curl "https://api.cropgraph.com/api/companions/tomato"

Look up the directed relationship between two crops. Returns { "found": false } if no edge exists in either direction.

Example

curl "https://api.cropgraph.com/api/check?a=tomato&b=basil"

Bed compatibility report for a group of crops. Surfaces every pairwise relationship (deduplicated) plus warnings for antagonist hubs.

Example

curl "https://api.cropgraph.com/api/plan?crops=tomato,basil,marigold,carrot"

Filter and list crops by category, season, and zone.

Example

curl "https://api.cropgraph.com/api/crops?category=herb&zone=8b"

Fuzzy search across slug, common name, scientific name, and aliases.

Example

curl "https://api.cropgraph.com/api/search?q=pepper"

Rotation family, year-gap, follow-with families, never-follow families, and citation for one crop.

Example

curl "https://api.cropgraph.com/api/rotation/tomato"

{
  "slug": "tomato",
  "family": "nightshades",
  "scientificFamily": "Solanaceae",
  "rotationYears": 3,
  "followWith": ["legumes", "grasses", "alliums"],
  "neverFollow": ["nightshades"],
  "reason": "…",
  "source": "…"
}

Validate a multi-year planting sequence. The first slug is year one, the second is year two, and so on. Returns each year's family, any violations, and an isValid flag.

Example

curl "https://api.cropgraph.com/api/rotation-check?sequence=tomato,bush-bean,sweet-corn,cabbage"

Frost-anchored succession chain for a crop slug or chain slug. Phases carry frost-relative day offsets; for concrete ISO dates, use /api/succession-plan.

Example

curl "https://api.cropgraph.com/api/succession/lettuce-leaf"

Succession chain resolved to concrete ISO dates for a coordinate. Pulls the chain by crop, resolves zone and climate from lat and lng, and projects each phase against the zone's frost dates.

Example

curl "https://api.cropgraph.com/api/succession-plan?crop=lettuce-leaf&lat=48.118&lng=-123.43"

Pests and diseases affecting a crop, sorted by severity then by pest slug. Each entry carries diagnostic symptoms, ordered organic management options, prevention notes, regions, and a citation.

Example

curl "https://api.cropgraph.com/api/pests/tomato"

Full detail for one pest or disease across every crop it affects, including aggregated severities and regions.

Example

curl "https://api.cropgraph.com/api/pest/tomato-hornworm"

Composite "now what?" report after a pest is identified. Returns severity verdict (foe / nuisance / cosmetic), immediate action steps, seasonal prevention practices, companion plant deterrents and trap crops, the full list of beneficial predators and parasitoids with the wait-before-spraying guidance, and friend-or-foe lookalikes. When the optional plant parameter is supplied, the response includes crop-specific symptoms and rotation advice for that crop. The endpoint powering the consumer pest-identification "now what?" moment.

Example

curl "https://api.cropgraph.com/api/pest-intelligence?pest=tomato-hornworm&plant=tomato"

Full detail for one beneficial insect, microbe, or friend-not-foe invertebrate. Returns identification cues, garden role, habitat needs, the plants that attract this beneficial, the crops it protects via prey relationships, and concrete protection tips. Categories covered: predator, parasitoid, pollinator, decomposer, microbial-control. Backed by a 200-entry beneficial insects fixture from Xerces Society, Cornell Cooperative Extension, UC IPM, UF/IFAS, USDA-ARS sources.

Example

curl "https://api.cropgraph.com/api/beneficial/seven-spotted-ladybug"

Browse the full beneficial insects catalog or a category-filtered subset. Sorted alphabetically by common name.

Example

curl "https://api.cropgraph.com/api/beneficials?category=parasitoid"

Friend-or-foe classification for any insect, microbe, or invertebrate slug. Checks the beneficial-insects database first, then the pest-disease database. Useful as a routing call before deciding whether to call /api/beneficial/:slug or /api/pest-intelligence. Returns one of: friend, foe, nuisance, cosmetic, neutral.

Example

curl "https://api.cropgraph.com/api/verdict/seven-spotted-ladybug"

USDA SSURGO soil profile for a coordinate. Returns the soil series, drainage class, surface texture, pH range across the profile, organic-matter level at the surface horizon, rooting depth, and a recommendations array cross-referenced with crop preferences. This is the only endpoint that calls an upstream service (USDA NRCS Soil Data Access). It is cached aggressively (one week) because SSURGO is static.

Example

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

{
  "coordinates": { "lat": 48.118, "lng": -123.43 },
  "mukey": "73450",
  "component": { "name": "Clallam", "percent": 85 },
  "soilType": "Clallam gravelly sandy loam, 0 to 15 percent slopes",
  "drainageClass": "Moderately well drained",
  "texture": "sandy loam",
  "ph": { "min": 5.8, "max": 5.8 },
  "organicMatter": "moderate",
  "depth": "very deep (152+ inches)",
  "recommendations": ["Drains acceptably…", "Slightly acidic…"],
  "source": "USDA NRCS Soil Survey Geographic Database (SSURGO), via SDA REST"
}

The killer endpoint. One call traverses every graph dimension at the requested coordinate: hardiness zone, climate type, frost dates, USDA SSURGO soil profile, climate-aware planting windows, growing-degree-day harvest prediction, succession chains, rotation families, top pests with organic management, and bed-level companion and antagonist analysis. The garden-app developer makes one call and gets the complete plan. Soil outages and unknown crops degrade gracefully so the response stays useful in every case.

Example

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

{
  "location": {
    "coordinates": { "lat": 48.118, "lng": -123.43 },
    "zone": "8b",
    "zoneNumber": 8,
    "climateType": "maritime",
    "frostDates": { "lastSpring": "03-15", "firstFall": "11-30" },
    "seasonDays": 260,
    "soil": {
      "soilType": "Clallam gravelly sandy loam, 0 to 15 percent slopes",
      "drainageClass": "Moderately well drained",
      "texture": "sandy loam",
      "ph": { "min": 5.8, "max": 5.8 },
      "organicMatter": "moderate"
    },
    "soilError": null
  },
  "crops": [
    {
      "slug": "tomato",
      "commonName": "Tomato",
      "category": "vegetable",
      "season": "warm",
      "planting": { "action": "start_indoors", "windowStart": "2026-01-04", "windowEnd": "2026-02-01", "inWindow": true },
      "harvest": {
        "daysToHarvest": { "min": 55, "max": 90 },
        "estimatedHarvestDate": "2026-07-29",
        "latestHarvestDate": "2026-09-01",
        "gddBased": true,
        "gddAccumulated": 1205,
        "confidence": "moderate",
        "baseTemp": 50,
        "gddRange": { "min": 1200, "max": 1800 }
      },
      "succession": { "hasChain": false, "phases": 1, "summary": "Single planting, no succession needed" },
      "rotation": { "family": "nightshades", "rotationYears": 3, "followWith": ["legumes", "grasses", "alliums"], "neverFollow": [] },
      "pests": [
        { "pest": "late-blight", "severity": "severe", "topManagement": "Copper preventive on the 5-day forecast" },
        { "pest": "tomato-hornworm", "severity": "high", "topManagement": "Handpick + Bt spray" }
      ],
      "soilNotes": "Slightly acidic; nightshades prefer pH 6.0 to 6.8. Add calcium (lime or gypsum) to reduce blossom end rot risk."
    }
  ],
  "unknownCrops": [],
  "bedAnalysis": {
    "companions": [
      { "a": "tomato", "b": "basil", "type": "beneficial", "mechanism": "pest_repellent", "strength": "strong" }
    ],
    "antagonists": [],
    "warnings": [],
    "rotationConflicts": []
  },
  "year": 2026,
  "source": "CropGraph v1.5. USDA Cooperative Extension, NRCS SSURGO, NOAA Climate Normals 1991-2020."
}

Growing-degree-day harvest prediction for a crop at a coordinate. Returns the earliest cultivar harvest date (when accumulated GDD reaches the model's min threshold), the latest cultivar harvest date (when GDD reaches max), monthly heat-unit accumulation, the base-temperature model used, and a confidence band. Falls back to NOAA Climate Normals 1991-2020 by zone and climate when no daily temperatures are supplied. 120 crops carry literature-grounded GDD models; for crops without a model, use /api/crop/:slug and the daysToHarvest field instead.

Example

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

{
  "crop": "tomato",
  "commonName": "Tomato",
  "plantDate": "2026-05-15",
  "location": { "zone": "8b", "zoneNumber": 8, "climateType": "maritime" },
  "gddModel": { "baseTemp": 50, "gddToMaturity": { "min": 1200, "max": 1800 } },
  "prediction": {
    "estimatedHarvestEarliest": "2026-08-07",
    "estimatedHarvestLatest": "2026-09-13",
    "monthlyGddAccumulation": [
      { "month": "May", "gdd": 136 },
      { "month": "Jun", "gdd": 390 },
      { "month": "Jul", "gdd": 558 },
      { "month": "Aug", "gdd": 558 },
      { "month": "Sep", "gdd": 169 }
    ],
    "totalGddEarliest": 1210,
    "totalGddLatest": 1811,
    "confidence": "moderate"
  },
  "source": "NOAA Climate Normals 1991-2020, CropGraph GDD models v1.5."
}