### Soil Profile Response Example

Source: https://cropgraph.com/docs

Example JSON response for the /api/soil endpoint, detailing soil characteristics and recommendations.

```json
{
  "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"
}
```

--------------------------------

### GET /api/garden-plan

Source: https://cropgraph.com/docs

Generates a complete garden plan for a given coordinate, considering various environmental factors and user-specified crops. This endpoint is designed to be a single call for developers to get all necessary garden planning information.

```APIDOC
## GET /api/garden-plan

### Description
Generates a complete garden plan for a given coordinate, considering various environmental factors and user-specified crops. This endpoint is designed to be a single call for developers to get all necessary garden planning information.

### Method
GET

### Endpoint
/api/garden-plan

### Parameters
#### Query Parameters
- **lat** (number) - required - Latitude in decimal degrees.
- **lng** (number) - required - Longitude in decimal degrees.
- **crops** (string) - required - Comma-separated list of crop slugs (or common names; `findCrop` matches both). Up to 20 per request. Unknown slugs are returned in `unknownCrops`; the rest of the plan continues.
- **year** (integer) - optional - 4-digit year for the planting plan. Defaults to the current year.
- **climate** (string) - optional - Override the auto-detected climate type. One of `maritime`, `mediterranean`, `continental`, `humid_subtropical`, `arid`, `semi_arid`.
- **include_soil** (boolean) - optional - Pass `false` to skip the SSURGO upstream call (faster responses, no soil block). Defaults to `true`.
- **previous_crops** (string) - optional - Comma-separated CSV of last year's bed sequence. When supplied, `bedAnalysis.rotationConflicts` flags family collisions against the current crop list.

### Request Example
```
https://api.cropgraph.com/api/garden-plan?lat=48.118&lng=-123.43&crops=tomato,basil,carrot
```
```

--------------------------------

### GET /api/succession-plan

Source: https://cropgraph.com/docs

Resolves a succession chain to concrete ISO dates for a specified coordinate, considering zone and climate.

```APIDOC
## GET /api/succession-plan

### Description
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.

### Method
GET

### Endpoint
/api/succession-plan

### Parameters
#### Query Parameters
- **crop** (string) - required - Crop slug, primary crop, or chain slug.
- **lat** (number) - required - Latitude in decimal degrees.
- **lng** (number) - required - Longitude in decimal degrees.
- **climate** (string) - optional - Override the detected climate type. One of: `maritime`, `mediterranean`, `continental`, `humid_subtropical`, `arid`, `semi_arid`.
- **year** (integer) - optional - 4-digit anchor year. Defaults to the current UTC year.

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

--------------------------------

### Get Pests by Crop (npm)

Source: https://cropgraph.com/docs

Use this function from `@cropgraph/core` to get a list of pests affecting a specific crop.

```javascript
import { getPestsByCrop } from "@cropgraph/core";

// Example usage:
const pests = getPestsByCrop("tomato");
```

--------------------------------

### GET /api/planting

Source: https://cropgraph.com/docs

Provides a planting plan for a given coordinate, including companion and antagonist information for each suggested crop.

```APIDOC
## GET /api/planting

### Description
Provides a planting plan for a given coordinate, including companion and antagonist information for each suggested crop. It can be filtered by date, climate, category, and indoor inclusion.

### Method
GET

### Endpoint
/api/planting

### Parameters
#### Query Parameters
- **lat** (number) - required - Latitude.
- **lng** (number) - required - Longitude.
- **date** (string) - optional - ISO date (`YYYY-MM-DD`). Defaults to today UTC.
- **climate** (string) - optional - Override climate. One of `maritime`, `mediterranean`, `continental`, `humid_subtropical`, `arid`, `semi_arid`.
- **category** (string) - optional - Restrict by category. One of `vegetable`, `herb`, `fruit`, `flower`, `cover-crop`, `root`, `legume`.
- **include_indoor** (boolean) - optional - `true` to include indoor-only crops.

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

--------------------------------

### GET /api/rotation-check

Source: https://cropgraph.com/docs

Validates a multi-year planting sequence for crop rotation compliance.

```APIDOC
## GET /api/rotation-check

### Description
Validates 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.

### Method
GET

### Endpoint
/api/rotation-check

### Parameters
#### Query Parameters
- **sequence** (string) - required - Comma-separated crop slugs in planting order. Minimum two crops required.

### Request Example
```
curl "https://api.cropgraph.com/api/rotation-check?sequence=tomato,basil,marigold"
```
```

--------------------------------

### Get Rotation Advice (npm)

Source: https://cropgraph.com/docs

Use this function from `@cropgraph/core` to retrieve rotation advice for a specific crop slug.

```javascript
import { getRotationAdvice } from "@cropgraph/core";

// Example usage:
const advice = getRotationAdvice("corn");
```

--------------------------------

### GET /api/beneficials?category=

Source: https://cropgraph.com/docs

Browses beneficial insects by category.

```APIDOC
## GET /api/beneficials?category=

### Description
Browses beneficial insects by category.

### Method
GET

### Endpoint
/api/beneficials

#### Query Parameters
- **category** (string) - Optional - The category of beneficial insects to list (e.g., `predator`, `pollinator`).
```

--------------------------------

### Get Succession Plan (npm)

Source: https://cropgraph.com/docs

Use this function from `@cropgraph/core` to generate a succession plan based on crop, zone, and climate.

```javascript
import { getSuccessionPlan } from "@cropgraph/core";

// Example usage:
const plan = getSuccessionPlan({ slug: "carrots", zone: "8b", climateType: "maritime" });
```

--------------------------------

### Get Pests with Deterrents (npm)

Source: https://cropgraph.com/docs

Use this function from `@cropgraph/core` to find pests that have specific deterrents for a given crop.

```javascript
import { getPestsWithDeterrents } from "@cropgraph/core";

// Example usage:
const pestsWithDeterrents = getPestsWithDeterrents("beans");
```

--------------------------------

### GET /api/plan

Source: https://cropgraph.com/docs

Generates a bed compatibility report for a group of crops, highlighting pairwise relationships and potential antagonist issues.

```APIDOC
## GET /api/plan

### Description
Generates a bed compatibility report for a group of crops. Surfaces every pairwise relationship (deduplicated) plus warnings for antagonist hubs.

### Method
GET

### Endpoint
/api/plan

### Parameters
#### Query Parameters
- **crops** (string) - required - Comma-separated slugs. Minimum two crops required.

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

--------------------------------

### Get Succession Chain (npm)

Source: https://cropgraph.com/docs

Use this function from `@cropgraph/core` to retrieve a succession chain for a given crop slug.

```javascript
import { getSuccessionChain } from "@cropgraph/core";

// Example usage:
const chain = getSuccessionChain("lettuce");
```

--------------------------------

### Get Planting Plan for a Coordinate

Source: https://cropgraph.com/docs

Retrieve a planting plan for a given coordinate, including suggestions, companions, and antagonists. Supports optional date, climate, category, and indoor crop inclusion.

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

--------------------------------

### Crop Details Response

Source: https://cropgraph.com/docs

Example JSON response for the /api/crop/:slug endpoint, showing crop information, companions, and antagonists.

```json
{
  "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" }
  ]
}
```

--------------------------------

### Get Pest Detail (npm)

Source: https://cropgraph.com/docs

Use this function from `@cropgraph/core` to retrieve detailed information about a specific pest.

```javascript
import { getPestDetail } from "@cropgraph/core";

// Example usage:
const pestInfo = getPestDetail("aphids");
```

--------------------------------

### Get Crop Succession Plan with Dates

Source: https://cropgraph.com/docs

Resolve a crop succession chain to concrete ISO dates based on latitude and longitude. Optionally override the climate and specify the anchor year.

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

--------------------------------

### Get Rotation Partners (npm)

Source: https://cropgraph.com/docs

Use this function from `@cropgraph/core` to find suitable rotation partners for a given crop slug.

```javascript
import { getRotationPartners } from "@cropgraph/core";

// Example usage:
const partners = getRotationPartners("tomatoes");
```

--------------------------------

### Get Organic Management (npm)

Source: https://cropgraph.com/docs

Use this function from `@cropgraph/core` to find organic management options for a given crop and pest.

```javascript
import { getOrganicManagement } from "@cropgraph/core";

// Example usage:
const management = getOrganicManagement("cabbage", "cabbage-worm");
```

--------------------------------

### Get Bed Compatibility Report

Source: https://cropgraph.com/docs

Generate a bed compatibility report for a group of crops. This report includes all pairwise relationships and warnings for antagonist hubs.

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

--------------------------------

### GET /api/check

Source: https://cropgraph.com/docs

Checks the directed relationship between two crops, returning whether a compatibility or antagonism exists.

```APIDOC
## GET /api/check

### Description
Checks the directed relationship between two crops. Returns `{ "found": false }` if no edge exists in either direction.

### Method
GET

### Endpoint
/api/check

### Parameters
#### Query Parameters
- **a** (string) - required - Crop slug or name.
- **b** (string) - required - Crop slug or name.

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

--------------------------------

### GET /api/pest-intelligence

Source: https://cropgraph.com/docs

Retrieves a composite report on pest intelligence, allowing filtering by pest and plant.

```APIDOC
## GET /api/pest-intelligence?pest=&plant=

### Description
Retrieves a composite report on pest intelligence, allowing filtering by pest and plant.

### Method
GET

### Endpoint
/api/pest-intelligence

#### Query Parameters
- **pest** (string) - Optional - The pest to filter the report by.
- **plant** (string) - Optional - The plant to filter the report by.
```

--------------------------------

### GET /api/companions/:slug

Source: https://cropgraph.com/docs

Fetches companion and antagonist information for a specific crop, including cited mechanisms and strengths.

```APIDOC
## GET /api/companions/:slug

### Description
Fetches companion and antagonist information for a specific crop, including cited mechanisms and strengths.

### Method
GET

### Endpoint
/api/companions/:slug

### Parameters
#### Path Parameters
- **slug** (string) - required - The slug or identifier for the crop.

### Request Example
```
curl "https://api.cropgraph.com/api/companions/tomato"
```
```

--------------------------------

### GET /api/verdict/:slug

Source: https://cropgraph.com/docs

Classifies an insect as friend or foe based on its slug.

```APIDOC
## GET /api/verdict/:slug

### Description
Classifies an insect as friend or foe based on its slug.

### Method
GET

### Endpoint
/api/verdict/:slug

#### Path Parameters
- **slug** (string) - Required - The unique identifier (slug) of the insect to classify.
```

--------------------------------

### GET /api/beneficial/:slug

Source: https://cropgraph.com/docs

Fetches detailed information for a specific beneficial insect, microbe, or invertebrate.

```APIDOC
## GET /api/beneficial/:slug

### Description
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.

### Method
GET

### Endpoint
/api/beneficial/:slug

### Parameters
#### Path Parameters
- **slug** (string) - required - Beneficial insect slug (path segment), e.g. `seven-spotted-ladybug`, `braconid-wasp-cotesia-congregata`, `blue-orchard-mason-bee`, `bt-kurstaki`.

### Request Example
```curl
https://api.cropgraph.com/api/beneficial/seven-spotted-ladybug
```
```

--------------------------------

### GET /api/succession/:slug

Source: https://cropgraph.com/docs

Retrieves the frost-anchored succession chain for a given crop or chain slug. Phases include frost-relative day offsets.

```APIDOC
## GET /api/succession/:slug

### Description
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`.

### Method
GET

### Endpoint
/api/succession/:slug

### Parameters
#### Path Parameters
- **slug** (string) - required - Crop slug, primary crop, or chain slug (path segment), e.g. `lettuce-leaf`.

### Request Example
```curl
https://api.cropgraph.com/api/succession/lettuce-leaf
```
```

--------------------------------

### GET /api/beneficial/:slug

Source: https://cropgraph.com/docs

Retrieves full details for a specific beneficial insect using its slug.

```APIDOC
## GET /api/beneficial/:slug

### Description
Retrieves full details for a specific beneficial insect using its slug.

### Method
GET

### Endpoint
/api/beneficial/:slug

#### Path Parameters
- **slug** (string) - Required - The unique identifier (slug) of the beneficial insect.
```

--------------------------------

### GET /api/garden-plan

Source: https://cropgraph.com/docs

Retrieves a garden plan for a specified location and a list of crops. The plan includes details about the location's climate, soil, and specific information for each crop such as planting and harvest windows, and pest management.

```APIDOC
## GET /api/garden-plan

### Description
Retrieves a garden plan for a specified location and a list of crops. The plan includes details about the location's climate, soil, and specific information for each crop such as planting and harvest windows, and pest management.

### Method
GET

### Endpoint
/api/garden-plan

### Parameters
#### Query Parameters
- **lat** (number) - Required - Latitude in decimal degrees.
- **lng** (number) - Required - Longitude in decimal degrees.
- **crops** (string) - Required - Comma-separated list of crop slugs or common names.

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

### Response
#### Success Response (200)
- **location** (object) - Information about the geographical location.
- **crops** (array) - Details for each requested crop.
- **unknownCrops** (array) - List of crops that were not recognized.
- **bedAnalysis** (object) - Analysis of crop companions and antagonists.
- **year** (integer) - The year for which the plan is generated.

#### Response Example
```json
{
  "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."
}
```
```

--------------------------------

### GET /api/pest/:slug

Source: https://cropgraph.com/docs

Fetches detailed information for a specific pest or disease across all crops it affects.

```APIDOC
## GET /api/pest/:slug

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

### Method
GET

### Endpoint
/api/pest/:slug

### Parameters
#### Path Parameters
- **slug** (string) - required - Pest or disease slug (path segment), e.g. `tomato-hornworm`.

### Request Example
```curl
https://api.cropgraph.com/api/pest/tomato-hornworm
```
```

--------------------------------

### GET /api/crops

Source: https://cropgraph.com/docs

Filters and lists available crops based on category, season, and USDA zone.

```APIDOC
## GET /api/crops

### Description
Filters and lists crops by category, season, and zone.

### Method
GET

### Endpoint
/api/crops

### Parameters
#### Query Parameters
- **category** (string) - optional - One of: `vegetable`, `herb`, `fruit`, `flower`, `cover-crop`, `root`, `legume`.
- **season** (string) - optional - One of: `cool`, `warm`, `perennial`, `biennial`.
- **zone** (string) - optional - USDA zone like `8b`.
- **limit** (integer) - optional - Integer 1..1000. Default 100.

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

--------------------------------

### Crop Rotation Information Response

Source: https://cropgraph.com/docs

Example JSON response for the /api/rotation/:slug endpoint, detailing rotation properties and sources.

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

--------------------------------

### Get Crops Affected by Pest (npm)

Source: https://cropgraph.com/docs

Use this function from `@cropgraph/core` to find which crops are affected by a specific pest.

```javascript
import { getCropsAffected } from "@cropgraph/core";

// Example usage:
const affectedCrops = getCropsAffected("spider-mites");
```

--------------------------------

### Get Companions and Antagonists for a Crop

Source: https://cropgraph.com/docs

Retrieve the companions and antagonists for a specific crop, including cited mechanisms and strengths.

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

--------------------------------

### Get Crop Succession Chain

Source: https://cropgraph.com/docs

Retrieve the frost-anchored succession chain for a specific crop slug. This provides a chain with frost-relative day offsets.

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

--------------------------------

### GET /api/rotation/:slug

Source: https://cropgraph.com/docs

Retrieves rotation family, year-gap, follow-with families, and never-follow families for a specific crop.

```APIDOC
## GET /api/rotation/:slug

### Description
Retrieves rotation family, year-gap, follow-with families, never-follow families, and citation for one crop.

### Method
GET

### Endpoint
/api/rotation/:slug

### Parameters
#### Path Parameters
- **slug** (string) - required - Crop slug from the calendar (path segment), e.g. `tomato`.

### Request Example
```
curl "https://api.cropgraph.com/api/rotation/tomato"
```

### Response
#### Success Response (200)
- **slug** (string) - The crop slug.
- **family** (string) - The crop's rotation family.
- **scientificFamily** (string) - The crop's scientific family.
- **rotationYears** (integer) - Recommended number of years before planting the same family again.
- **followWith** (array) - List of families recommended to plant after this crop.
- **neverFollow** (array) - List of families that should not be planted after this crop.
- **reason** (string) - Explanation for the rotation recommendations.
- **source** (string) - Citation for the rotation information.

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

--------------------------------

### Get Garden Plan

Source: https://cropgraph.com/docs

Retrieve a garden plan including crop details, planting and harvest information, and companion planting suggestions based on latitude, longitude, and a list of desired crops. This is useful for initial garden layout and planning.

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

```json
{
  "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."
}
```

--------------------------------

### GET /api/pest-intelligence

Source: https://cropgraph.com/docs

Provides a comprehensive 'now what?' report for a pest, including action steps, prevention, and identification of beneficials or lookalikes.

```APIDOC
## GET /api/pest-intelligence

### Description
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.

### Method
GET

### Endpoint
/api/pest-intelligence

### Parameters
#### Query Parameters
- **pest** (string) - required - Pest or disease slug, e.g. `tomato-hornworm`, `aphid-cabbage`, `late-blight`.
- **plant** (string) - optional - Crop slug or common name to scope the intelligence: returns crop-specific symptoms and rotation family advice when supplied.

### Request Example
```curl
https://api.cropgraph.com/api/pest-intelligence?pest=tomato-hornworm&plant=tomato
```
```

--------------------------------

### GET /api/beneficials

Source: https://cropgraph.com/docs

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

```APIDOC
## GET /api/beneficials

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

### Method
GET

### Endpoint
/api/beneficials

### Parameters
#### Query Parameters
- **category** (string) - optional - Filter by functional category. One of: `predator`, `parasitoid`, `pollinator`, `decomposer`, `microbial-control`.

### Request Example
```curl
https://api.cropgraph.com/api/beneficials?category=parasitoid
```
```

--------------------------------

### Get Full Crop Details

Source: https://cropgraph.com/docs

Retrieve detailed information about a specific crop, including its companions and antagonists. The slug can match the crop's slug, common name, scientific name, or alias.

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

--------------------------------

### GET /api/search

Source: https://cropgraph.com/docs

Performs a fuzzy search across crop slugs, common names, scientific names, and aliases.

```APIDOC
## GET /api/search

### Description
Performs a fuzzy search across slug, common name, scientific name, and aliases.

### Method
GET

### Endpoint
/api/search

### Parameters
#### Query Parameters
- **q** (string) - required - Query string.
- **limit** (integer) - optional - Integer 1..100. Default 20.

### Request Example
```
curl "https://api.cropgraph.com/api/search?q=pepper"
```
```

--------------------------------

### GET /api/crop/:slug

Source: https://cropgraph.com/docs

Retrieves full crop details, including companions and antagonists, by providing a crop's slug.

```APIDOC
## GET /api/crop/:slug

### Description
Retrieves full crop details, including companions and antagonists, by providing a crop's slug. The slug is matched against the crop's slug, common name, scientific name, or alias. Returns 404 if no match is found.

### Method
GET

### Endpoint
/api/crop/:slug

### Parameters
#### Path Parameters
- **slug** (string) - required - The slug or identifier for the crop.

### Request Example
```
curl "https://api.cropgraph.com/api/crop/tomato"
```

### Response
#### Success Response (200)
- **crop** (object) - Details of the crop including slug, commonName, and scientificName.
- **companions** (array) - A list of companion crops, including their type, mechanism, and strength.
- **antagonists** (array) - A list of antagonist crops.

#### Response Example
```json
{
  "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" }
  ]
}
```
```

--------------------------------

### Get Crop Rotation Information

Source: https://cropgraph.com/docs

Retrieve rotation family, year-gap, follow-with families, and never-follow families for a specific crop. The slug is a path segment, e.g., `tomato`.

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

--------------------------------

### GET /api/verdict/:slug

Source: https://cropgraph.com/docs

Classifies an insect, microbe, or invertebrate slug as 'friend', 'foe', 'nuisance', 'cosmetic', or 'neutral'.

```APIDOC
## GET /api/verdict/:slug

### Description
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`.

### Method
GET

### Endpoint
/api/verdict/:slug

### Parameters
#### Path Parameters
- **slug** (string) - required - Insect or microbe slug (path segment), e.g. `seven-spotted-ladybug`, `tomato-hornworm`.

### Request Example
```curl
https://api.cropgraph.com/api/verdict/seven-spotted-ladybug
```
```

--------------------------------

### Get USDA Hardiness Zone and Climate Data

Source: https://cropgraph.com/docs

Retrieve USDA hardiness zone, climate type, frost dates, and season length for a given coordinate. Requires latitude and longitude.

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

--------------------------------

### GET /api/zone

Source: https://cropgraph.com/docs

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

```APIDOC
## GET /api/zone

### Description
Retrieves USDA hardiness zone, climate type, frost dates, and season length for a coordinate.

### Method
GET

### Endpoint
/api/zone

### Parameters
#### Query Parameters
- **lat** (number) - required - Latitude in decimal degrees. Range `-90..90`.
- **lng** (number) - required - Longitude in decimal degrees. Range `-180..180`.

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

### Response
#### Success Response (200)
- **coordinates** (object) - Latitude and longitude of the queried coordinate.
- **zone** (object) - USDA hardiness zone details including zone, number, subzone, minTempF, and maxTempF.
- **frostDates** (object) - Frost date information including zone, lastSpring, and firstFall dates, and seasonDays.
- **seasonDays** (integer) - The number of frost-free days in the growing season.
- **climateType** (string) - The climate type for the given coordinate (e.g., 'maritime').

#### Response Example
```json
{
  "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"
}
```
```

--------------------------------

### GET /api/pests/:slug

Source: https://cropgraph.com/docs

Retrieves pests and diseases affecting a specific crop, sorted by severity. Includes diagnostic symptoms and management options.

```APIDOC
## GET /api/pests/:slug

### Description
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.

### Method
GET

### Endpoint
/api/pests/:slug

### Parameters
#### Path Parameters
- **slug** (string) - required - Crop slug (path segment), e.g. `tomato`.

### Request Example
```curl
https://api.cropgraph.com/api/pests/tomato
```
```

--------------------------------

### USDA Hardiness Zone and Climate Data Response

Source: https://cropgraph.com/docs

Example JSON response for the /api/zone endpoint, detailing coordinates, hardiness zone, frost dates, season length, and climate type.

```json
{
  "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"
}
```

--------------------------------

### Get Soil Profile by Coordinates

Source: https://cropgraph.com/docs

Retrieve detailed USDA SSURGO soil profile information for a given latitude and longitude. This endpoint is cached for one week.

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

--------------------------------

### Get Pest Intelligence Report

Source: https://cropgraph.com/docs

Generate a 'now what?' report after identifying a pest. This includes severity verdicts, action steps, prevention practices, and beneficial predator information. Optionally scope by plant for crop-specific details.

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

--------------------------------

### Get Pests and Diseases for a Crop

Source: https://cropgraph.com/docs

Retrieve a list of pests and diseases affecting a specific crop, sorted by severity. Each entry includes symptoms, management options, and prevention notes.

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

--------------------------------

### Get Full Detail for a Pest or Disease

Source: https://cropgraph.com/docs

Obtain comprehensive details for a single pest or disease, including aggregated severities and affected regions across all crops.

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

--------------------------------

### Get Friend-or-Foe Verdict

Source: https://cropgraph.com/docs

Classify any insect, microbe, or invertebrate slug as 'friend', 'foe', 'nuisance', 'cosmetic', or 'neutral'. This endpoint checks both beneficial and pest databases.

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

--------------------------------

### GET /api/soil

Source: https://cropgraph.com/docs

Retrieves USDA SSURGO soil profile information for a given coordinate. This endpoint provides details about the soil series, drainage class, texture, pH, organic matter, rooting depth, and crop recommendations.

```APIDOC
## GET /api/soil

### Description
Retrieves USDA SSURGO soil profile information for a given coordinate. This endpoint provides details about the soil series, drainage class, texture, pH, organic matter, rooting depth, and crop recommendations.

### Method
GET

### Endpoint
/api/soil

### Parameters
#### Query Parameters
- **lat** (number) - required - Latitude in decimal degrees. SSURGO covers the United States and its territories; points outside US coverage return 404.
- **lng** (number) - required - Longitude in decimal degrees.

### Request Example
```
https://api.cropgraph.com/api/soil?lat=48.118&lng=-123.43
```

### Response
#### Success Response (200)
- **coordinates** (object) - The input coordinates.
- **mukey** (string) - The soil map unit key.
- **component** (object) - Information about the dominant soil component.
  - **name** (string) - The name of the soil component.
  - **percent** (number) - The percentage of this component in the soil profile.
- **soilType** (string) - The classification of the soil type.
- **drainageClass** (string) - The drainage class of the soil.
- **texture** (string) - The surface texture of the soil.
- **ph** (object) - The pH range of the soil profile.
  - **min** (number) - The minimum pH value.
  - **max** (number) - The maximum pH value.
- **organicMatter** (string) - The organic matter level at the surface horizon.
- **depth** (string) - The rooting depth of the soil.
- **recommendations** (array) - An array of recommendations cross-referenced with crop preferences.
- **source** (string) - The source of the soil data.

#### Response Example
```json
{
  "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"
}
```
```

--------------------------------

### Get Beneficial Insect Details

Source: https://cropgraph.com/docs

Retrieve full details for a specific beneficial insect, microbe, or invertebrate. This includes identification cues, garden role, habitat needs, and protection tips.

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