> ## Documentation Index
> Fetch the complete documentation index at: https://docs.climatifai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# How crop aptitude scoring works

> Learn how AgroRisk combines seven climate and soil factors into a single 0–100 aptitude score for any supported crop and location.

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                               | 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 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

| 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

The `season` 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)                         |

<Tip>
  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.
</Tip>

## Supported crops

Pass any of the following identifiers in the `crop_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 from `GET api.climatifai.com/agri/advisor?lat=20.5&lon=-101.0&crop_id=maiz&season=annual`:

```json theme={null}
{
  "crop_id": "maiz",
  "crop_name": "Maíz",
  "score": 74,
  "aptitude": "Alta",
  "recommendation_text": "La zona tiene condiciones climáticas favorables para el cultivo de Maíz.",
  "factors": [
    {
      "name": "Precipitación anual",
      "value": 682.4,
      "unit": "mm/año",
      "score": 88,
      "weight": 0.20,
      "status": "ok",
      "ideal": "500–800 mm"
    },
    {
      "name": "Temperatura media",
      "value": 21.3,
      "unit": "°C",
      "score": 92,
      "weight": 0.15,
      "status": "ok",
      "ideal": "10–35 °C"
    },
    {
      "name": "Humedad del suelo",
      "value": 0.198,
      "unit": "m³/m³",
      "score": 79,
      "weight": 0.15,
      "status": "ok",
      "ideal": ">0.15 m³/m³"
    },
    {
      "name": "Aptitud biofísica (GAEZ)",
      "value": 90,
      "unit": "%",
      "score": 90,
      "weight": 0.25,
      "status": "ok",
      "ideal": "Alta aptitud en zona"
    },
    {
      "name": "pH del suelo",
      "value": null,
      "unit": "",
      "score": 65,
      "weight": 0.10,
      "status": "warning",
      "ideal": "5.5–7.5"
    },
    {
      "name": "Exposición a incendios",
      "value": 0,
      "unit": "hotspots/semana",
      "score": 100,
      "weight": 0.10,
      "status": "ok",
      "ideal": "0 hotspots"
    },
    {
      "name": "Rendimiento histórico",
      "value": null,
      "unit": "",
      "score": 70,
      "weight": 0.05,
      "status": "ok",
      "ideal": "Datos FAOSTAT no disponibles"
    }
  ],
  "_cache": {
    "hit": true,
    "stale": false
  }
}
```

<Note>
  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.
</Note>