Machine Learning API, FildraAI

What is the Machine Learning API?

The Machine Learning API gives you direct access to the prediction models that power FildraAI's agronomic intelligence. Rather than going through a conversational interface, you can call these models programmatically, submitting structured farm data and receiving structured predictions in return.

All endpoints support both a basic (result-only) mode and a with-trace mode that returns a step-by-step explanation of the model's reasoning. The trace is designed to help agronomists and extension officers verify model outputs and explain recommendations to farmers in their own words.

Transparent predictions

Every prediction from the Machine Learning API can be accompanied by a reasoning trace. This is not a post-hoc explanation, it is the model's actual decision path, making the result verifiable and auditable.

Authentication

All Machine Learning API endpoints require a valid API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Your key must have the machine_learning API enabled and carry the machine_learning:predict scope. All ML inference endpoints are billed per call. Locale can be passed in the request body, as a query parameter, or via the Accept-Language header, the body takes precedence.

Endpoints

POST /api/v1/ml/crop/basic

Returns a crop recommendation based on soil and climate features. Result only, no reasoning trace.

POST /api/v1/ml/crop/with_trace

Crop recommendation with a full reasoning trace. Includes the feature importances and decision path the model used to reach its recommendation.

POST /api/v1/ml/yield/basic

Yield prediction given fertilizer usage and soil/climate conditions. Returns predicted yield range. Result only.

POST /api/v1/ml/snapshot

Combined endpoint. Runs crop recommendation, yield analysis, or both in a single call. Useful for generating a complete farm intelligence snapshot with minimal round-trips.

Crop recommendation

The crop recommendation endpoints accept a features object describing the farm's soil chemistry and climate. The model returns one of 22 supported crop classes with a calibrated confidence score.

Model overview

Random Forest classifier (n_estimators=100, max_depth=15) trained on the public Crop_recommendation dataset (Kaggle), an India-derived synthetic agronomic dataset of 2,200 balanced samples, 100 per crop class. Test accuracy on a held-out 20% split is 99.55%, with 5-fold cross-validation at 99.45% ± 0.23%. Inputs are standardised internally; you submit raw values.

Scope and honest caveats

Because the training dataset is synthetic and India-derived, predictions reflect general agronomic relationships rather than country-specific guidance. Treat the result as a reference signal that an agronomist should cross-check against local conditions, available varieties, and market access. The country field is metadata only, it is not a model input and does not change the prediction.

Required fields

features (object), All seven numeric fields below are required

Optional fields

country (string), ISO-3166-1 alpha-2 code, e.g. ZM, KE, IN. Stored as metadata; does not change the prediction.
locale (string), Response language locale key, e.g. en-us, sw-ke, pt-ao

Input parameters features

All seven fields below are required inside the features object. Out-of-range values are accepted by the API but will produce predictions outside the model's training distribution and should not be trusted.

Field	Unit	Training range	Description
N	kg/ha	0 – 140	Soil nitrogen content reading. This is a soil-test measurement, not a fertilizer application rate.
P	kg/ha	5 – 145	Soil phosphorus content reading.
K	kg/ha	5 – 205	Soil potassium content reading.
temperature	°C	8.8 – 43.7	Average ambient temperature for the growing season.
humidity	% RH	14.3 – 100	Average relative humidity, expressed as a percentage.
ph	unitless	3.5 – 9.9	Soil pH. 7 is neutral; below 7 is acidic, above is alkaline.
rainfall	mm / season	20.2 – 298.6	Total rainfall over the growing season (not per month, not per year).

Supported crops (22 classes) output

The model returns exactly one of these classes as the top prediction, with up to two runner-ups when called via the with_trace variant.

Cereals & staples

rice
maize

Legumes & pulses

chickpea
kidneybeans
pigeonpeas
mothbeans
mungbean
blackgram
lentil

Fruits

pomegranate
banana
mango
grapes
watermelon
muskmelon
apple
orange
papaya
coconut

Cash & specialty crops

cotton
jute
coffee

Example request
POST /api/v1/ml/crop/with_trace
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "features": {
    "N": 90,
    "P": 42,
    "K": 43,
    "temperature": 21.0,
    "humidity": 82.0,
    "ph": 6.5,
    "rainfall": 202.9
  },
  "country": "ZM",
  "locale": "en-us"
}
        

Yield analysis

The yield endpoint estimates maize yield in kilograms per hectare given fertilizer application rates, soil properties, and climate inputs. The with_trace variant additionally accepts a target_yield and budget for fertilizer optimisation.

Model overview

XGBoost regressor (n_estimators=100, max_depth=6, learning_rate=0.1) trained on the Harvard Dataverse Sub-Saharan Africa Maize Trials dataset, 12,049 site-level observations after outlier removal, spanning 1,216 unique trial sites. Test R² is 0.66 with MAPE around 31.5%. Cross-validated R² is lower (~0.09), so treat absolute yield numbers as directional rather than precise. The model is most informative for comparing scenarios (e.g. fertilizer A vs B) on a single field.

Scope and honest caveats

Trained on maize trials only and Sub-Saharan Africa only. Do not use this model for other crops or regions without independent validation. The country field is metadata; predictions are not localised at inference time.

Required fields

fertilizer (object), Elemental nutrient application rates (see parameter table)
soil_climate (object), Soil and climate conditions for the field
crop_features (object), Must include crop: "maize". Other fields are optional context.

Optional fields

extra_context.target_yield (number, kg/ha), Used by with_trace to compute the fertilizer rates needed to reach this target.
extra_context.budget (number, USD/ha), Constrains the fertilizer optimiser to a maximum input spend.
country (string), ISO-3166-1 alpha-2 code. Metadata only.
locale (string), Response language

fertilizer object required

Fertilizer rates are expressed as elemental kilograms per hectare. The optimiser searches N ∈ [0, 150], P ∈ [0, 60], K ∈ [0, 60] when called via with_trace.

Field	Unit	Training range	Description
nitrogen_kg_ha	kg N/ha	0 – 338	Nitrogen applied as elemental N. Convert from product (e.g. urea is 46% N) before submitting.
phosphorus_kg_ha	kg P/ha	0 – 150	Phosphorus applied as elemental P.
potassium_kg_ha	kg K/ha	0 – 318	Potassium applied as elemental K.
application_method	enum	broadcast · banded · split	How fertilizer was applied.
organic_matter_added	boolean	true / false	Whether organic matter (manure, compost) was added.

soil_climate object required

Field-level soil and climate inputs. soil_type is matched internally to soil chemistry features the model was trained on.

Field	Unit	Training range	Description
soil_type	enum	sandy · loamy · clay · silty · sandy_loam · clay_loam	Soil texture class.
soil_ph	unitless	4.75 – 8.25	Soil pH measurement.
rainfall_mm	mm / season	205 – 2,646	Total rainfall over the growing season.
temperature_c	°C	12 – 29	Mean temperature for the growing season.
altitude_m	m a.s.l.	0 – 3,000+	Field altitude above sea level.
irrigation_available	boolean	true / false	Whether irrigation is available on the field.

crop_features object required

Identifies the crop and field context. For the yield model, crop must be "maize".

Field	Unit	Accepted values	Description
crop	string	"maize"	Crop being analysed. The yield model only supports "maize".
variety	string	free text	Variety or cultivar name, e.g. SC627. Free-text.
planting_density	plants / ha	25,000 – 60,000 (typical maize)	Planting density in plants per hectare.
land_size_ha	hectares	> 0	Field area being analysed.
growth_stage	enum	vegetative · tasselling · grain_fill · mature	Current growth stage.
previous_crop	string	crop name from supported list	Crop grown on the same field in the previous season. Used for rotation context.

Example request
POST /api/v1/ml/yield/basic
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "fertilizer": {
    "nitrogen_kg_ha": 90,
    "phosphorus_kg_ha": 35,
    "potassium_kg_ha": 30,
    "application_method": "split",
    "organic_matter_added": true
  },
  "soil_climate": {
    "soil_type": "loamy",
    "soil_ph": 6.2,
    "rainfall_mm": 820,
    "temperature_c": 21.5,
    "altitude_m": 1150,
    "irrigation_available": false
  },
  "crop_features": {
    "crop": "maize",
    "variety": "SC627",
    "planting_density": 44000,
    "land_size_ha": 2.5,
    "previous_crop": "soybean"
  },
  "country": "ZM",
  "locale": "en-us"
}
        

Combined ML snapshot

POST /api/v1/ml/snapshot runs multiple models in a single call. All input objects are optional, supply only what you have, and the snapshot runs the models it can support. include_traces: true returns reasoning traces for every model that ran.

When called with both fertilizer + soil_climate + crop_features (with crop: "maize"), the snapshot returns yield prediction plus fertilizer optimisation. If you additionally supply the 7 crop-recommendation features inside crop_features.recommendation_features, the snapshot also returns a top-3 crop recommendation.

Example snapshot request
POST /api/v1/ml/snapshot
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "fertilizer": {
    "nitrogen_kg_ha": 90,
    "phosphorus_kg_ha": 35,
    "potassium_kg_ha": 30,
    "application_method": "split",
    "organic_matter_added": true
  },
  "soil_climate": {
    "soil_type": "loamy",
    "soil_ph": 6.2,
    "rainfall_mm": 820,
    "temperature_c": 21.5,
    "altitude_m": 1150,
    "irrigation_available": false
  },
  "crop_features": {
    "crop": "maize",
    "variety": "SC627",
    "planting_density": 44000,
    "land_size_ha": 2.5,
    "recommendation_features": {
      "N": 90, "P": 42, "K": 43,
      "temperature": 21.0, "humidity": 82.0,
      "ph": 6.5, "rainfall": 202.9
    }
  },
  "extra_context": {
    "target_yield": 5000,
    "budget": 220
  },
  "include_traces": true,
  "country": "ZM",
  "locale": "en-us"
}
        

Reasoning traces

The with_trace variants and the include_traces: true snapshot option return a structured explanation of the model's reasoning alongside the prediction. This includes:

Feature importance

Which input features (e.g. soil pH, nitrogen level, rainfall) most strongly influenced the prediction, expressed as relative weights.

Decision path

The step-by-step path through the model's decision logic, showing which thresholds or rules were applied to reach the final output.

Confidence score

A calibrated confidence score for the top prediction, indicating how strongly the model's training supports this recommendation for the given inputs.

Alternatives

Runner-up recommendations with their scores, helping agronomists consider fallback options if the primary recommendation is not feasible.

How to use traces

Traces are designed for agronomist review and farmer communication, not for raw display to end users. Use the feature importance data to explain to a farmer why a particular crop was recommended given their soil conditions. If the top feature is rainfall and the farmer has irrigation, the recommendation may need to be reconsidered locally.

Error codes

The Machine Learning API maps service errors to standard HTTP status codes:

Client errors (4xx)

400, Invalid or missing input object (e.g. missing features, invalid field type)
401, Missing or invalid API key
403, Key lacks the required scope
429, Rate limit exceeded

Server errors (5xx)

500, Model inference failed (internal error)
503, ML service temporarily unavailable; retry with backoff
504, Inference timeout; the model took longer than the allowed window