Predict

Predict

POST /v1/predict

Returns survival predictions for a single site, species, and planting method across available time horizons.

This is the core of Canopi’s intelligence. Given a location, species, and planting method, the API returns the probability of survival at 1, 3, and 5 years, along with the top environmental risk factors driving the prediction.

Request

Headers

Header	Required	Description
X-API-Key	Yes	Your Canopi API key
Content-Type	Yes	application/json

Body

{
  "latitude": 44.12,
  "longitude": -122.03,
  "species_code": "PSME",
  "planting_method": "manual",
  "horizons": [1, 3, 5]
}

Field	Type	Required	Description
latitude	float	Yes	Latitude (-90 to 90)
longitude	float	Yes	Longitude (-180 to 180)
species_code	string	Yes	Species code. See Species reference.
planting_method	string	Yes	"manual" or "drone_seeded"
horizons	integer[]	No	Subset of [1, 3, 5]. Defaults to all three.

Response

{
  "site": {
    "latitude": 44.12,
    "longitude": -122.03,
    "matched_latitude": 44.1087,
    "matched_longitude": -122.0451,
    "match_distance_km": 1.82,
    "region": "pnw"
  },
  "species_code": "PSME",
  "species_common_name": "Douglas Fir",
  "planting_method": "manual",
  "predictions": [
    {
      "horizon_years": 1,
      "survival_probability": 0.94,
      "risk_factors": [
        {"factor": "Vapor pressure deficit", "impact": "negative", "magnitude": 0.089},
        {"factor": "Precipitation", "impact": "positive", "magnitude": 0.072},
        {"factor": "Soil water capacity", "impact": "positive", "magnitude": 0.054}
      ]
    },
    {
      "horizon_years": 3,
      "survival_probability": 0.87,
      "risk_factors": [
        {"factor": "Vapor pressure deficit", "impact": "negative", "magnitude": 0.112},
        {"factor": "Dew point temperature", "impact": "negative", "magnitude": 0.098},
        {"factor": "Elevation", "impact": "negative", "magnitude": 0.067}
      ]
    },
    {
      "horizon_years": 5,
      "survival_probability": 0.81,
      "risk_factors": [
        {"factor": "Dew point temperature", "impact": "negative", "magnitude": 0.167},
        {"factor": "Precipitation", "impact": "negative", "magnitude": 0.125},
        {"factor": "Crown ratio", "impact": "negative", "magnitude": 0.117}
      ]
    }
  ],
  "model": {
    "version": "pnw_v0_2_mycel",
    "codename": "mycel",
    "series": "Mycelium"
  },
  "generated_at": "2026-06-25T14:30:00Z"
}

Response fields

Field	Description
site.matched_latitude / matched_longitude	The coordinates of the nearest data point Canopi matched to your requested location.
site.match_distance_km	Distance in kilometers between your requested coordinates and the matched data point. Lower is better.
predictions[].survival_probability	Probability of tree survival at this horizon, from 0.0 (certain mortality) to 1.0 (certain survival).
predictions[].risk_factors	Top 3 environmental factors influencing survival, ranked by magnitude. See Risk Factors.
model.version	The model that generated this prediction.

Error responses

Code	HTTP	Cause
outside_coverage	422	Coordinates are outside Oregon/Washington
no_nearby_data	422	Inside coverage but no data point within search radius
invalid_species	422	Species code not recognized
invalid_method	422	Method not manual or drone_seeded

See Errors for the full error reference.

Example: Comparing a coastal site vs. an inland site

import httpx

headers = {"X-API-Key": "cnpi_live_your_api_key_here"}

# Coastal site — Tillamook State Forest, Oregon
coastal = httpx.post(
    "https://api.canopitech.ai/v1/predict",
    headers=headers,
    json={
        "latitude": 45.65,
        "longitude": -123.60,
        "species_code": "PISI",  # Sitka Spruce — coastal specialist
        "planting_method": "manual"
    }
).json()

# Inland site — Deschutes National Forest, Oregon
inland = httpx.post(
    "https://api.canopitech.ai/v1/predict",
    headers=headers,
    json={
        "latitude": 43.80,
        "longitude": -121.50,
        "species_code": "PIPO",  # Ponderosa Pine — dry-side specialist
        "planting_method": "manual"
    }
).json()

print(f"Sitka Spruce (coast): {coastal['predictions'][2]['survival_probability']:.0%} at 5yr")
print(f"Ponderosa Pine (inland): {inland['predictions'][2]['survival_probability']:.0%} at 5yr")