When you callDocumentation Index
Fetch the complete documentation index at: https://docs.climatifai.com/llms.txt
Use this file to discover all available pages before exploring further.
/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 | Weight | Source |
|---|---|---|---|
| 1 | Annual precipitation adequacy | 20% | Open-Meteo ERA5 |
| 2 | Mean temperature fit | 15% | Open-Meteo ERA5 |
| 3 | Soil moisture / water stress | 15% | Open-Meteo ERA5 |
| 4 | Biophysical suitability (GAEZ proxy) | 25% | Derived from temp + precip |
| 5 | Soil pH compatibility | 10% | Provided or fallback |
| 6 | Fire and flood exposure | 10% | NASA FIRMS |
| 7 | Historical yield proxy | 5% | Static fallback (MVP) |
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 idealprecip_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
| Label | Score range | Meaning |
|---|---|---|
Alta | ≥ 70 | Conditions are favourable for this crop |
Media | 45–69 | Viable with appropriate management |
Baja | < 45 | Significant climate or soil risk |
Season parameter
Theseason query parameter controls which months of historical data are used when computing the factors:
| Value | Months included |
|---|---|
lluvias | Rainy season (approx. May–October in most of LATAM) |
secas | Dry season (approx. November–April) |
annual | Full year average (default) |
Supported crops
Pass any of the following identifiers in thecrop_id parameter. English aliases are automatically resolved to their canonical Spanish IDs.
| Canonical ID | English alias | Crop |
|---|---|---|
maiz | maize | Maize (Zea mays) |
trigo | wheat | Wheat (Triticum aestivum) |
cafe | coffee | Coffee (Coffea arabica) |
soya | soybean | Soybean (Glycine max) |
vid | vineyard | Grapevine (Vitis vinifera) |
frijol | bean | Common Bean (Phaseolus vulgaris) |
papa | potato | Potato (Solanum tuberosum) |
arroz | rice | Rice (Oryza sativa) |
cana | sugarcane | Sugarcane (Saccharum officinarum) |
tomate | tomato | Tomato (Solanum lycopersicum) |
cebolla | onion | Onion (Allium cepa) |
ajo | garlic | Garlic (Allium sativum) |
girasol | sunflower | Sunflower (Helianthus annuus) |
sorgo | sorghum | Sorghum (Sorghum bicolor) |
algodon | cotton | Cotton (Gossypium hirsutum) |
quinua | quinoa | Quinoa (Chenopodium quinoa) |
aguacate | avocado | Avocado (Persea americana) |
cacao | — | Cacao (Theobroma cacao) |
chile | — | Chili pepper (Capsicum annuum) |
banano | — | Banana (Musa acuminata) |
yuca | — | Cassava (Manihot esculenta) |
cardamomo | — | Cardamom (Elettaria cardamomum) |
Sample response
The following is a representative response fromGET 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.