cropl 0.1.2

Python SDK for cropl — crop yield prediction powered by satellite imagery and machine learning

cropl

Python SDK for cropl — crop yield prediction powered by satellite imagery and machine learning.

Predict crop yields by providing location, crop, and planting information. Built for developers, actuaries, insurers, and government agencies who need programmatic access to yield forecasts.

Preview Release — This is the demo/preview version of the cropl SDK. It uses a local prediction engine with realistic modeled outputs calibrated from a pilot across 847 fields in 28 states. Production API with real satellite data and live model inference is coming soon.

Installation

pip install cropl

For DataFrame support:

pip install cropl[pandas]

Quickstart

import cropl

result = cropl.predict(
    location="Story County, IA",
    crop="corn",
    planting_date="2026-04-15",
)

print(f"Predicted yield: {result.yield_value} {result.yield_unit}")
print(f"Confidence: {result.confidence}%")
print(result.summary())

API Reference

cropl.predict()

Generate a single crop yield prediction.

result = cropl.predict(
    # Required
    location="Story County, IA",  # County+state, zip code, or FIPS code
    crop="corn",                   # corn, soybeans, wheat, cotton, rice
    planting_date="2026-04-15",    # YYYY-MM-DD

    # Optional
    irrigation="rainfed",          # rainfed, center_pivot, drip, flood
    tillage="conventional",        # conventional, no_till, strip_till, reduced
    temp_adjustment=0,             # -10 to +10 (°F offset from historical avg)
    rain_adjustment=0,             # -50 to +50 (% offset from historical avg)
    field_acres=None,              # float — enables revenue estimate
)

Returns: PredictionResult with:

Attribute	Type	Description
yield_value	float	Predicted yield (e.g., 191.3)
yield_unit	str	Unit — bu/acre, lb/acre, or cwt/acre
confidence	float	Confidence score (0–100)
mape	float	Model error rate for this crop/region
location	str	Resolved location name
county	str	County name
state	str	State abbreviation
fips	str	FIPS code
crop	str	Crop name
planting_date	str	Input planting date
growth_projection	list[dict]	Monthly yield progression
ndvi_timeline	list[dict]	Monthly NDVI values
factors	list[dict]	Contributing factors with impact scores
revenue_estimate	float | None	Revenue estimate (if field_acres provided)
price_per_unit	float	Market price used for revenue calc
timestamp	str	ISO timestamp of prediction

Convenience methods:

result.to_dict()       # dict representation
result.to_json()       # JSON string
result.to_dataframe()  # pandas DataFrame (single row)
result.summary()       # formatted string for printing

cropl.predict_batch()

Run multiple predictions at once.

results = cropl.predict_batch([
    {"location": "Story County, IA", "crop": "corn", "planting_date": "2026-04-15"},
    {"location": "50011", "crop": "soybeans", "planting_date": "2026-05-20"},
    {"location": "20135", "crop": "wheat", "planting_date": "2026-09-10"},
])
# Returns: list[PredictionResult]

cropl.predict_dataframe()

Run predictions from a pandas DataFrame.

import pandas as pd

df = pd.DataFrame([
    {"location": "Story County, IA", "crop": "corn", "planting_date": "2026-04-15"},
    {"location": "50011", "crop": "soybeans", "planting_date": "2026-05-20"},
])
results_df = cropl.predict_dataframe(df)

# Custom column names
results_df = cropl.predict_dataframe(
    df,
    location_col="county",
    crop_col="crop",
    date_col="plant_date",
)

cropl.list_crops()

List all supported crops with metadata.

crops = cropl.list_crops()
# [
#     {"name": "corn", "yield_unit": "bu/acre", "base_yield": 187.3, "planting_season": "Apr-May"},
#     {"name": "soybeans", "yield_unit": "bu/acre", "base_yield": 51.2, "planting_season": "May-Jun"},
#     ...
# ]

cropl.model_accuracy()

Get model accuracy metrics for a crop and region.

acc = cropl.model_accuracy(crop="corn", region="corn_belt")
# {"mape": 8.1, "rmse": 18.4, "accuracy_pct": 92, "r_squared": 0.87, "sample_size": 312}

cropl.market_price()

Get current market price for a crop.

price = cropl.market_price(crop="corn")
# {"crop": "corn", "price": 4.53, "unit": "$/bu", "source": "USDA", "as_of": "2026-03-01"}

cropl.resolve_location()

Resolve a location string to county, state, FIPS, and region.

loc = cropl.resolve_location("50011")
# {"county": "Story County", "state": "IA", "fips": "19169", "region": "corn_belt"}

Supported Crops

Crop	Base Yield	Unit	Planting Season
Corn	~187	bu/acre	Apr–May
Soybeans	~51	bu/acre	May–Jun
Wheat	~52	bu/acre	Sep–Oct
Cotton	~884	lb/acre	Apr–Jun
Rice	~75	cwt/acre	Mar–Apr

Location Formats

Three input formats are supported:

Format	Example
County + State	"Story County, IA" or "Story, Iowa"
Zip Code	"50011"
FIPS Code	"19169"

All formats resolve internally to county + state + FIPS code.

Revenue Estimation

Pass field_acres to get a revenue estimate based on predicted yield and current market prices:

result = cropl.predict(
    location="Story County, IA",
    crop="corn",
    planting_date="2026-04-15",
    field_acres=160,
)
print(f"Estimated revenue: ${result.revenue_estimate:,.2f}")

Production API

This preview SDK uses a local prediction engine. The production version connects to cropl's API with real satellite imagery, weather data, and trained ML models.

When the production API is available:

import cropl

# Switch to production API — same predict() interface
cropl.configure(api_key="your-api-key")

result = cropl.predict(
    location="Story County, IA",
    crop="corn",
    planting_date="2026-04-15",
)

Visit cropl.co to learn more.

License

Copyright 2026 cropl. All rights reserved.