Batch Predict

Batch Predict

POST /v1/predict/batch

Returns predictions for multiple sites in a single request. Each site can specify a different species and planting method.

Batch limits depend on your tier: Spore allows 10 sites per call, Mycel allows 100, and Hypha allows 500.

Request

{
  "requests": [
    {
      "latitude": 44.12,
      "longitude": -122.03,
      "species_code": "PSME",
      "planting_method": "manual"
    },
    {
      "latitude": 45.52,
      "longitude": -121.78,
      "species_code": "TSHE",
      "planting_method": "drone_seeded"
    },
    {
      "latitude": 43.80,
      "longitude": -121.50,
      "species_code": "PIPO",
      "planting_method": "manual"
    }
  ]
}

Each object in the requests array follows the same schema as the single Predict endpoint.

Response

{
  "results": [
    {
      "site": {...},
      "species_code": "PSME",
      "species_common_name": "Douglas Fir",
      "planting_method": "manual",
      "predictions": [...],
      "model": {...},
      "generated_at": "..."
    },
    {
      "site": {...},
      "species_code": "TSHE",
      "species_common_name": "Western Hemlock",
      "planting_method": "drone_seeded",
      "predictions": [...],
      "model": {...},
      "generated_at": "..."
    },
    {
      "site": {...},
      "species_code": "PIPO",
      "species_common_name": "Ponderosa Pine",
      "planting_method": "manual",
      "predictions": [...],
      "model": {...},
      "generated_at": "..."
    }
  ],
  "summary": {
    "total": 3,
    "successful": 3,
    "failed": 0
  }
}

Partial failures

If some requests in a batch fail (e.g., one site is outside coverage), the batch still returns 200. Failed requests appear in the results array with an error object instead of predictions:

{
  "error": {
    "code": "outside_coverage",
    "message": "This location (33.70, -84.30) is beyond Canopi's current root network."
  },
  "latitude": 33.7,
  "longitude": -84.3
}

The summary.failed count reflects how many requests produced errors.

Use case: Site selection ranking

import httpx

# Candidate planting sites from a field survey
candidates = [
    {"latitude": 44.12, "longitude": -122.03},
    {"latitude": 44.35, "longitude": -122.15},
    {"latitude": 44.08, "longitude": -121.89},
    {"latitude": 44.52, "longitude": -122.31},
    {"latitude": 44.27, "longitude": -121.95},
]

response = httpx.post(
    "https://api.canopitech.ai/v1/predict/batch",
    headers={"X-API-Key": "cnpi_live_your_api_key_here"},
    json={
        "requests": [
            {**site, "species_code": "PSME", "planting_method": "manual"}
            for site in candidates
        ]
    }
).json()

# Rank by 5-year survival probability
ranked = sorted(
    response["results"],
    key=lambda r: r["predictions"][2]["survival_probability"],
    reverse=True
)

for i, result in enumerate(ranked, 1):
    prob = result["predictions"][2]["survival_probability"]
    lat = result["site"]["latitude"]
    lng = result["site"]["longitude"]
    print(f"{i}. ({lat}, {lng}) — {prob:.0%} five-year survival")