Consuming Insights Engine APIs

Overview

The Insights Engine API provides agronomic model predictions. This guide details how to integrate and consume these APIs. For authentication details, see the Token Generation Guide. The API is designed to be user-friendly, allowing you to easily access agronomic model predictions. The following sections provide information on the API's base URL, authentication, request structure, and sample requests.

API Details

Base URL

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": "avizio",
                    "version": "v1.0",
                    "metadata": {
                        "business_rule_country_code": "FR"
                    }
                }
            ]
        }
    ]
}

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

curl --location 'https://api.insights.cropwise.com/v2.0/predictions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <your-token>' \
--data '{
    "request_version": "v1.0",
    "fields": [
        {
            "models": [
                {
                    "name": "avizio",
                    "version": "v1.0",
                    "metadata": {
                        "business_rule_country_code": "FR"
                    }
                }
            ],
            "location": {
                "type": "Feature",
                "geometry": {
                    "type": "Point",
                    "coordinates": [
                        5.3168865738,
                        49.6685693248
                    ]
                }
            },
            "crop": "WINTER_BARLEY",
            "crop_variety": {
                "name": "ABONDANCE",
                "traits": [
                    {
                        "category": "agronomic",
                        "type": "disease_resistance",
                        "disease_code": "ERYSGR",
                        "value": 6.0
                    },
                    {
                        "category": "agronomic",
                        "type": "disease_resistance", 
                        "disease_code": "COCHSA",
                        "value": 5.0
                    },
                    {
                        "category": "agronomic",
                        "type": "disease_resistance",
                        "disease_code": "PYRNTE",
                        "value": 5.0
                    },
                    {
                        "category": "agronomic",
                        "type": "disease_resistance",
                        "disease_code": "RHYNSE",
                        "value": 3.0
                    },
                    {
                        "category": "agronomic",
                        "type": "disease_resistance",
                        "disease_code": "PUCCHD",
                        "value": 5.0
                    },
                    {
                        "category": "agronomic",
                        "type": "disease_resistance",
                        "disease_code": "RAMUCC",
                        "value": 7.0
                    },
                    {
                        "category": "agronomic",
                        "type": "vernalization",
                        "value": 8.0
                    },
                    {
                        "category": "agronomic",
                        "type": "elongation_earlyness",
                        "value": 3.0
                    },
                    {
                        "category": "agronomic",
                        "type": "flowering_earlyness",
                        "value": 7.5
                    },
                    {
                        "category": "agronomic",
                        "type": "height",
                        "value": 4.5
                    }
                ]
            },
            "planting": {
                "date": "2021-10-10T00:00:00Z"
            },
            "soil": {
                "practice": "TILL",
                "texture": "LOAMY_SAND",
                "nitrogen": {
                    "value": 120,
                    "unit": "kg/ha"
                },
                "calcareous": false,
                "organic": false
            },
            "observations": [
                {
                    "category": "yield_potential",
                    "yield_potential": {
                        "value": "75",
                        "unit": "q/ha"
                    }
                },
                {
                    "category": "crop_history",
                    "values": [
                        {
                            "harvest_date": "2019-01-01T00:00:00Z",
                            "crops": [
                                "CORN"
                            ]
                        },
                        {
                            "harvest_date": "2020-01-01T00:00:00Z",
                            "crops": [
                                "OILSEED RAPE"
                            ]
                        }
                    ]
                }
            ],
            "applications": [
                {
                    "sequence": 1,
                    "date": "2022-04-05T00:00:00Z",
                    "products": [
                        {
                            "name": "COMET 200",
                            "rate_of_use": {
                                "value": 0.2,
                                "unit": "L/ha"
                            },
                            "diseases": [
                                {
                                    "code": "PSDCHA",
                                    "is_effective": false
                                },
                                {
                                    "code": "ERYSGR",
                                    "is_effective": false
                                },
                                {
                                    "code": "GIBBZE",
                                    "is_effective": false
                                }
                            ]
                        },
                        {
                            "name": "CURBATUR",
                            "rate_of_use": {
                                "value": 0.4,
                                "unit": "L/ha"
                            },
                            "diseases": [
                                {
                                    "code": "PSDCHA",
                                    "is_effective": true
                                },
                                {
                                    "code": "ERYSGR",
                                    "is_effective": true
                                },
                                {
                                    "code": "GIBBZE",
                                    "is_effective": true
                                }
                            ]
                        }
                    ]
                },
                {
                    "sequence": 2,
                    "date": "2022-04-25T00:00:00Z",
                    "products": [
                        {
                            "name": "CERATAVO ERA",
                            "rate_of_use": {
                                "value": 0.55,
                                "unit": "L/ha"
                            },
                            "diseases": [
                                {
                                    "code": "PSDCHA",
                                    "is_effective": false
                                },
                                {
                                    "code": "ERYSGR",
                                    "is_effective": false
                                },
                                {
                                    "code": "GIBBZE",
                                    "is_effective": true
                                }
                            ]
                        },
                        {
                            "name": "TWIST 500 SC",
                            "rate_of_use": {
                                "value": 0.11,
                                "unit": "L/ha"
                            },
                            "diseases": [
                                {
                                    "code": "PSDCHA",
                                    "is_effective": false
                                },
                                {
                                    "code": "ERYSGR",
                                    "is_effective": true
                                },
                                {
                                    "code": "GIBBZE",
                                    "is_effective": true
                                }
                            ]
                        }
                    ]
                }
            ]
        }
    ]
}'

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:

Rate Limiting

Currently, there are no rate limits specifically for Insights Engine endpoints. However, please note that Farm Settings API rate limits may affect end users accessing these endpoints.