Skip to main content
When you call /agri/advisor, the API computes a weighted aptitude score that reflects how well a location’s climate and soil conditions match a specific crop’s requirements. The result is a single number between 0 and 100, a plain-language label, and a breakdown of every factor that contributed to the score so you can understand exactly what is limiting or supporting production in that location.

​
The scoring formula

The final score is a weighted sum of seven factors. Each factor produces a sub-score from 0 to 100, and those sub-scores are multiplied by their weights and summed together.

​
Factor details

1. Annual precipitation adequacy (20%) The API sums mean monthly precipitation across the selected season window to estimate annualised rainfall, then scores how close that total falls to the crop’s ideal precip_min_mm–precip_max_mm range. A value in the center of the range scores 100; values outside the range are penalised proportionally. 2. Mean temperature (15%) Average temperature across the season is compared against the crop’s temp_min_c–temp_max_c envelope. The scoring is centred on the midpoint of that range, so the ideal score is achieved near temp_opt_c. 3. Soil moisture / water stress (15%) The API uses the ERA5 soil_moisture variable (volumetric water content in m³/m³) averaged over the season. The conversion is min(100, avg_soil_moisture × 400), meaning 0.25 m³/m³ maps to 100. If soil moisture data is unavailable, a neutral fallback of 60 is applied. 4. Biophysical suitability — GAEZ proxy (25%) This factor combines the temperature sub-score and the precipitation sub-score with equal weight (50/50) to approximate the FAO GAEZ land suitability classification. It is the highest-weighted single factor because it captures the combined climate envelope most relevant to crop biology. 5. Soil pH compatibility (10%) If you supply a soil_ph value (via the GraphQL soil field or a direct measurement), the API scores it against the crop’s soil_ph_min–soil_ph_max range using the same centred scoring function. When no pH value is available, a neutral fallback of 65 is used. 6. Fire and flood exposure (10%) The number of NASA FIRMS hotspots detected within the query radius in the past week is converted to a penalty: fire_score = max(0, 100 − hotspot_count × 10). Ten or more hotspots within the search area produce a score of 0 for this factor. 7. Historical yield proxy (5%) Actual FAOSTAT yield data integration is planned. In the current MVP, this factor returns a fixed score of 70 for all crops and locations. Because its weight is only 5%, it has minimal effect on the final score.

​
Aptitude labels

​
Season parameter

The season query parameter controls which months of historical data are used when computing the factors:
Use lluvias or secas when you want to evaluate a crop’s suitability for a specific growing window rather than the annual average. Selecting the right season improves the signal-to-noise ratio for temperature and precipitation scoring.

​
Supported crops

Pass any of the following identifiers in the crop_id parameter. English aliases are automatically resolved to their canonical Spanish IDs.

​
Sample response

The following is a representative response from GET api.climatifai.com/agri/advisor?lat=20.5&lon=-101.0&crop_id=maiz&season=annual:
The status field on each factor uses three values: ok (score ≥ 70), warning (45–69), and risk (< 45). Your application can use these to highlight limiting factors without re-implementing the scoring thresholds.