Consuming AgInsights Engine APIs
The AgInsights Engine API provides agronomic model predictions. This guide details how to integrate and consume these APIs.
Requirements:
API Details
Base URL
| Environment | URL |
|---|---|
| PROD | https://api.insights.cropwise.com |
Authentication
All requests require authentication using a Bearer token:
- Add
Authorization: Bearer <your-token>to the request headers
API Endpoint
Currently, there is one unified endpoint for all agronomic model predictions:
- Endpoint:
/v2.0/predictions - Method: POST
- Content-Type: application/json
Model Selection
To get predictions from a specific model, include the model details in your request:
{
"models": [
{
"name": "<model-name>",
"version": "<model-version>",
"metadata": {
"business_rule_country_code": "<country-code>"
}
}
]
}
Example Request
{
"request_version": "v1.0",
"fields": [
{
"models": [
{
"name": "phenological_model"
}
],
"location": {
"geometry": {
"type": "Point",
"coordinates": [
-98.008822,
41.182406
]
},
"type": "Feature"
},
"crop": "CORN",
"crop_variety": {
"relative_maturity": "RM113"
},
"planting": {
"date": "2025-5-1T00:00:00Z"
},
"soil": {
"texture_category": "Clay_Loam"
}
}
]
}
Request/Response Structure
For detailed information about request and response structures, please refer to the respective model cards in the documentation.
Sample Request
Curl Example with Full Payload
{
"response_version": "v1.0",
"results": [
{
"id": null,
"location": {
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [
-98.008822,
41.182406
]
},
"properties": {
"distance_to_grid": {
"unit": "km",
"value": 50
}
}
},
"metadata": {
"type": "algorithm",
"models": [
{
"metadata": {
"historical_time_period": {
"start": "2006-05-01T00:00:00Z",
"end": "2025-10-16T00:00:00Z"
}
},
"name": "phenological_model"
}
],
"result_time": 4.83
},
"predictions": [
{
"feature_category": "aggregated_growth_stage_simulations",
"features": [
{
"type": "growth_stage:Ritchie scale",
"value": "Germination"
},
{
"type": "growth_stage:BBCH",
"value": "1"
},
{
"type": "start_days_since_planting:mean",
"value": 0
},
{
"type": "start_days_since_planting:median",
"value": 0
},
{
"type": "start_days_since_planting:standard_deviation",
"value": 0.0
},
{
"type": "growth_stage:start_date",
"value": "2025-05-01T00:00:00Z"
}
],
"attributes": {
"warning": {
"targeted_years": 20,
"aggregated_years": 20,
"excluded_years": 0
}
}
},
{
"feature_category": "aggregated_growth_stage_simulations",
"features": [
{
"type": "growth_stage:Ritchie scale",
"value": "VE"
},
{
"type": "growth_stage:BBCH",
"value": "09-12"
},
{
"type": "start_days_since_planting:mean",
"value": 9
},
{
"type": "start_days_since_planting:median",
"value": 9
},
{
"type": "start_days_since_planting:standard_deviation",
"value": 0.0
},
{
"type": "growth_stage:start_date",
"value": "2025-05-10T00:00:00Z"
}
],
"attributes": {
"warning": {
"targeted_years": 20,
"aggregated_years": 20,
"excluded_years": 0
}
}
},
{
"feature_category": "aggregated_growth_stage_simulations",
"features": [
{
"type": "growth_stage:Ritchie scale",
"value": "V1"
},
{
"type": "growth_stage:BBCH",
"value": "13"
},
{
"type": "start_days_since_planting:mean",
"value": 10
},
{
"type": "start_days_since_planting:median",
"value": 10
},
{
"type": "start_days_since_planting:standard_deviation",
"value": 0.0
},
{
"type": "growth_stage:start_date",
"value": "2025-05-11T00:00:00Z"
}
],
"attributes": {
"warning": {
"targeted_years": 20,
"aggregated_years": 20,
"excluded_years": 0
}
}
},
{
"feature_category": "aggregated_growth_stage_simulations",
"features": [
{
"type": "growth_stage:Ritchie scale",
"value": "V2"
},
{
"type": "growth_stage:BBCH",
"value": "14"
},
{
"type": "start_days_since_planting:mean",
"value": 12
},
{
"type": "start_days_since_planting:median",
"value": 12
},
{
"type": "start_days_since_planting:standard_deviation",
"value": 0.0
},
{
"type": "growth_stage:start_date",
"value": "2025-05-13T00:00:00Z"
}
],
"attributes": {
"warning": {
"targeted_years": 20,
"aggregated_years": 20,
"excluded_years": 0
}
}
},
{
"feature_category": "aggregated_growth_stage_simulations",
"features": [
{
"type": "growth_stage:Ritchie scale",
"value": "V3"
},
{
"type": "growth_stage:BBCH",
"value": "15"
},
{
"type": "start_days_since_planting:mean",
"value": 18
},
{
"type": "start_days_since_planting:median",
"value": 18
},
{
"type": "start_days_since_planting:standard_deviation",
"value": 0.0
},
{
"type": "growth_stage:start_date",
"value": "2025-05-19T00:00:00Z"
}
],
"attributes": {
"warning": {
"targeted_years": 20,
"aggregated_years": 20,
"excluded_years": 0
}
}
},
{
"feature_category": "aggregated_growth_stage_simulations",
"features": [
{
"type": "growth_stage:Ritchie scale",
"value": "V4"
},
{
"type": "growth_stage:BBCH",
"value": "16"
},
{
"type": "start_days_since_planting:mean",
"value": 23
},
{
"type": "start_days_since_planting:median",
"value": 24
},
{
"type": "start_days_since_planting:standard_deviation",
"value": 0.433
},
{
"type": "growth_stage:start_date",
"value": "2025-05-25T00:00:00Z"
}
],
"attributes": {
"warning": {
"targeted_years": 20,
"aggregated_years": 20,
"excluded_years": 0
}
}
},
{
"feature_category": "aggregated_growth_stage_simulations",
"features": [
{
"type": "growth_stage:Ritchie scale",
"value": "V5"
},
{
"type": "growth_stage:BBCH",
"value": "17"
},
{
"type": "start_days_since_planting:mean",
"value": 30
},
{
"type": "start_days_since_planting:median",
"value": 30
},
{
"type": "start_days_since_planting:standard_deviation",
"value": 0.0
},
{
"type": "growth_stage:start_date",
"value": "2025-05-31T00:00:00Z"
}
],
"attributes": {
"warning": {
"targeted_years": 20,
"aggregated_years": 20,
"excluded_years": 0
}
}
},
{
"feature_category": "aggregated_growth_stage_simulations",
"features": [
{
"type": "growth_stage:Ritchie scale",
"value": "V6"
},
{
"type": "growth_stage:BBCH",
"value": "18"
},
{
"type": "start_days_since_planting:mean",
"value": 33
},
{
"type": "start_days_since_planting:median",
"value": 33
},
{
"type": "start_days_since_planting:standard_deviation",
"value": 0.0
},
{
"type": "growth_stage:start_date",
"value": "2025-06-03T00:00:00Z"
}
],
"attributes": {
"warning": {
"targeted_years": 20,
"aggregated_years": 20,
"excluded_years": 0
}
}
},
{
"feature_category": "aggregated_growth_stage_simulations",
"features": [
{
"type": "growth_stage:Ritchie scale",
"value": "V7"
},
{
"type": "growth_stage:BBCH",
"value": "19"
},
{
"type": "start_days_since_planting:mean",
"value": 37
},
{
"type": "start_days_since_planting:median",
"value": 37
},
{
"type": "start_days_since_planting:standard_deviation",
"value": 0.0
},
{
"type": "growth_stage:start_date",
"value": "2025-06-07T00:00:00Z"
}
],
"attributes": {
"warning": {
"targeted_years": 20,
"aggregated_years": 20,
"excluded_years": 0
}
}
},
{
"feature_category": "aggregated_growth_stage_simulations",
"features": [
{
"type": "growth_stage:Ritchie scale",
"value": "V8"
},
{
"type": "growth_stage:BBCH",
"value": "19"
},
{
"type": "start_days_since_planting:mean",
"value": 40
},
{
"type": "start_days_since_planting:median",
"value": 40
},
{
"type": "start_days_since_planting:standard_deviation",
"value": 0.0
},
{
"type": "growth_stage:start_date",
"value": "2025-06-10T00:00:00Z"
}
],
"attributes": {
"warning": {
"targeted_years": 20,
"aggregated_years": 20,
"excluded_years": 0
}
}
},
{
"feature_category": "aggregated_growth_stage_simulations",
"features": [
{
"type": "growth_stage:Ritchie scale",
"value": "V9"
},
{
"type": "growth_stage:BBCH",
"value": "19"
},
{
"type": "start_days_since_planting:mean",
"value": 43
},
{
"type": "start_days_since_planting:median",
"value": 43
},
{
"type": "start_days_since_planting:standard_deviation",
"value": 0.0
},
{
"type": "growth_stage:start_date",
"value": "2025-06-13T00:00:00Z"
}
],
"attributes": {
"warning": {
"targeted_years": 20,
"aggregated_years": 20,
"excluded_years": 0
}
}
},
{
"feature_category": "aggregated_growth_stage_simulations",
"features": [
{
"type": "growth_stage:Ritchie scale",
"value": "V10"
},
{
"type": "growth_stage:BBCH",
"value": "19"
},
{
"type": "start_days_since_planting:mean",
"value": 45
},
{
"type": "start_days_since_planting:median",
"value": 45
},
{
"type": "start_days_since_planting:standard_deviation",
"value": 0.0
},
{
"type": "growth_stage:start_date",
"value": "2025-06-15T00:00:00Z"
}
],
"attributes": {
"warning": {
"targeted_years": 20,
"aggregated_years": 20,
"excluded_years": 0
}
}
},
{
"feature_category": "aggregated_growth_stage_simulations",
"features": [
{
"type": "growth_stage:Ritchie scale",
"value": "V11"
},
{
"type": "growth_stage:BBCH",
"value": "19"
},
{
"type": "start_days_since_planting:mean",
"value": 48
},
{
"type": "start_days_since_planting:median",
"value": 48
},
{
"type": "start_days_since_planting:standard_deviation",
"value": 0.0
},
{
"type": "growth_stage:start_date",
"value": "2025-06-18T00:00:00Z"
}
],
"attributes": {
"warning": {
"targeted_years": 20,
"aggregated_years": 20,
"excluded_years": 0
}
}
},
{
"feature_category": "aggregated_growth_stage_simulations",
"features": [
{
"type": "growth_stage:Ritchie scale",
"value": "V12"
},
{
"type": "growth_stage:BBCH",
"value": "19"
},
{
"type": "start_days_since_planting:mean",
"value": 50
},
{
"type": "start_days_since_planting:median",
"value": 50
},
{
"type": "start_days_since_planting:standard_deviation",
"value": 0.433
},
{
"type": "growth_stage:start_date",
"value": "2025-06-20T00:00:00Z"
}
],
"attributes": {
"warning": {
"targeted_years": 20,
"aggregated_years": 20,
"excluded_years": 0
}
}
},
{
"feature_category": "aggregated_growth_stage_simulations",
"features": [
{
"type": "growth_stage:Ritchie scale",
"value": "V13"
},
{
"type": "growth_stage:BBCH",
"value": "19"
},
{
"type": "start_days_since_planting:mean",
"value": 53
},
{
"type": "start_days_since_planting:median",
"value": 53
},
{
"type": "start_days_since_planting:standard_deviation",
"value": 0.0
},
{
"type": "growth_stage:start_date",
"value": "2025-06-23T00:00:00Z"
}
],
"attributes": {
"warning": {
"targeted_years": 20,
"aggregated_years": 20,
"excluded_years": 0
}
}
},
{
"feature_category": "aggregated_growth_stage_simulations",
"features": [
{
"type": "growth_stage:Ritchie scale",
"value": "V14"
},
{
"type": "growth_stage:BBCH",
"value": "19"
},
{
"type": "start_days_since_planting:mean",
"value": 55
},
{
"type": "start_days_since_planting:median",
"value": 55
},
{
"type": "start_days_since_planting:standard_deviation",
"value": 0.0
},
{
"type": "growth_stage:start_date",
"value": "2025-06-25T00:00:00Z"
}
],
"attributes": {
"warning": {
"targeted_years": 20,
"aggregated_years": 20,
"excluded_years": 0
}
}
},
{
"feature_category": "aggregated_growth_stage_simulations",
"features": [
{
"type": "growth_stage:Ritchie scale",
"value": "VT"
},
{
"type": "growth_stage:BBCH",
"value": "59"
},
{
"type": "start_days_since_planting:mean",
"value": 69
},
{
"type": "start_days_since_planting:median",
"value": 70
},
{
"type": "start_days_since_planting:standard_deviation",
"value": 0.433
},
{
"type": "growth_stage:start_date",
"value": "2025-07-10T00:00:00Z"
}
],
"attributes": {
"warning": {
"targeted_years": 20,
"aggregated_years": 20,
"excluded_years": 0
}
}
},
{
"feature_category": "aggregated_growth_stage_simulations",
"features": [
{
"type": "growth_stage:Ritchie scale",
"value": "R1"
},
{
"type": "growth_stage:BBCH",
"value": "61"
},
{
"type": "start_days_since_planting:mean",
"value": 71
},
{
"type": "start_days_since_planting:median",
"value": 72
},
{
"type": "start_days_since_planting:standard_deviation",
"value": 0.433
},
{
"type": "growth_stage:start_date",
"value": "2025-07-12T00:00:00Z"
}
],
"attributes": {
"warning": {
"targeted_years": 20,
"aggregated_years": 20,
"excluded_years": 0
}
}
},
{
"feature_category": "aggregated_growth_stage_simulations",
"features": [
{
"type": "growth_stage:Ritchie scale",
"value": "R2"
},
{
"type": "growth_stage:BBCH",
"value": "71"
},
{
"type": "start_days_since_planting:mean",
"value": 80
},
{
"type": "start_days_since_planting:median",
"value": 81
},
{
"type": "start_days_since_planting:standard_deviation",
"value": 0.433
},
{
"type": "growth_stage:start_date",
"value": "2025-07-21T00:00:00Z"
}
],
"attributes": {
"warning": {
"targeted_years": 20,
"aggregated_years": 20,
"excluded_years": 0
}
}
},
{
"feature_category": "aggregated_growth_stage_simulations",
"features": [
{
"type": "growth_stage:Ritchie scale",
"value": "R3"
},
{
"type": "growth_stage:BBCH",
"value": "73"
},
{
"type": "start_days_since_planting:mean",
"value": 87
},
{
"type": "start_days_since_planting:median",
"value": 87
},
{
"type": "start_days_since_planting:standard_deviation",
"value": 0.0
},
{
"type": "growth_stage:start_date",
"value": "2025-07-27T00:00:00Z"
}
],
"attributes": {
"warning": {
"targeted_years": 20,
"aggregated_years": 20,
"excluded_years": 0
}
}
},
{
"feature_category": "aggregated_growth_stage_simulations",
"features": [
{
"type": "growth_stage:Ritchie scale",
"value": "R4"
},
{
"type": "growth_stage:BBCH",
"value": "83"
},
{
"type": "start_days_since_planting:mean",
"value": 94
},
{
"type": "start_days_since_planting:median",
"value": 95
},
{
"type": "start_days_since_planting:standard_deviation",
"value": 0.866
},
{
"type": "growth_stage:start_date",
"value": "2025-08-04T00:00:00Z"
}
],
"attributes": {
"warning": {
"targeted_years": 20,
"aggregated_years": 20,
"excluded_years": 0
}
}
},
{
"feature_category": "aggregated_growth_stage_simulations",
"features": [
{
"type": "growth_stage:Ritchie scale",
"value": "R5"
},
{
"type": "growth_stage:BBCH",
"value": "85"
},
{
"type": "start_days_since_planting:mean",
"value": 103
},
{
"type": "start_days_since_planting:median",
"value": 104
},
{
"type": "start_days_since_planting:standard_deviation",
"value": 0.433
},
{
"type": "growth_stage:start_date",
"value": "2025-08-13T00:00:00Z"
}
],
"attributes": {
"warning": {
"targeted_years": 20,
"aggregated_years": 20,
"excluded_years": 0
}
}
},
{
"feature_category": "aggregated_growth_stage_simulations",
"features": [
{
"type": "growth_stage:Ritchie scale",
"value": "R6"
},
{
"type": "growth_stage:BBCH",
"value": "87"
},
{
"type": "start_days_since_planting:mean",
"value": 118
},
{
"type": "start_days_since_planting:median",
"value": 119
},
{
"type": "start_days_since_planting:standard_deviation",
"value": 0.433
},
{
"type": "growth_stage:start_date",
"value": "2025-08-28T00:00:00Z"
}
],
"attributes": {
"warning": {
"targeted_years": 20,
"aggregated_years": 20,
"excluded_years": 0
}
}
}
]
}
]
}
Important Notes
Each model may require specific input parameters. Refer to model cards for:
- Required input fields
- Response structure
- Model-specific business rules
- Supported countries/regions
- Version information
Error Handling
The API returns standard HTTP status codes:
| Status Code | Description |
|---|---|
| 200 | Successful request |
| 400 | Bad request (invalid parameters) |
| 401 | Unauthorized (invalid token) |
| 403 | Forbidden |
| 500 | Server error |
| 502 | Bad gateway |
Rate Limiting
Currently, there are no rate limits specifically for AgInsights Engine endpoints. However, please note that Farm Settings API rate limits may affect end users accessing these endpoints.