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

# GET /agri/advisor — Crop aptitude score

> Score a specific crop's agricultural aptitude at any LATAM location using climate baselines, soil moisture, fire exposure, and biophysical suitability factors.

The crop advisor endpoint computes a weighted aptitude score (0–100) for a given crop at a geographic location. It pulls a five-year climate baseline (2019–2023) from Open-Meteo, overlays recent fire hotspot data from NASA FIRMS, and runs the scoring engine to produce a human-readable recommendation alongside a breakdown of individual scoring factors. You can call this endpoint to decide which crops to plant in a given area or to evaluate climate suitability before committing to a field.

## Endpoint

```text theme={null}
GET api.climatifai.com/agri/advisor
```

## Parameters

<ParamField query="lat" type="float" required>
  Center latitude of the location you want to evaluate. Decimal degrees, WGS 84.
</ParamField>

<ParamField query="lon" type="float" required>
  Center longitude of the location you want to evaluate. Decimal degrees, WGS 84.
</ParamField>

<ParamField query="crop_id" type="string" required>
  Identifier for the crop to score. The following canonical IDs are supported:

  | Canonical ID | Crop (ES)      | Crop (EN)   |
  | ------------ | -------------- | ----------- |
  | `maiz`       | Maíz           | Maize       |
  | `trigo`      | Trigo          | Wheat       |
  | `cafe`       | Café           | Coffee      |
  | `soya`       | Soya           | Soybean     |
  | `vid`        | Vid            | Grapevine   |
  | `frijol`     | Frijol         | Common Bean |
  | `papa`       | Papa           | Potato      |
  | `arroz`      | Arroz          | Rice        |
  | `cana`       | Caña de azúcar | Sugarcane   |
  | `tomate`     | Tomate         | Tomato      |
  | `cebolla`    | Cebolla        | Onion       |
  | `ajo`        | Ajo            | Garlic      |
  | `girasol`    | Girasol        | Sunflower   |
  | `sorgo`      | Sorgo          | Sorghum     |
  | `algodon`    | Algodón        | Cotton      |
  | `quinua`     | Quinua         | Quinoa      |
  | `aguacate`   | Aguacate       | Avocado     |

  English aliases are also accepted and automatically resolved to the canonical ID: `maize`, `wheat`, `coffee`, `soybean`, `vineyard`, `bean`, `potato`, `rice`, `sugarcane`, `tomato`, `onion`, `garlic`, `sunflower`, `sorghum`, `cotton`, `quinoa`, `avocado`.
</ParamField>

<ParamField query="season" default="annual" type="string">
  Season context for the score calculation. Accepted values: `lluvias` (rainy season), `secas` (dry season), `annual` (full-year average).
</ParamField>

<ParamField query="country_iso" type="string">
  Optional ISO 3166-1 alpha-2 country code for the location being queried. Must be a LATAM country code, excluding Brazil (`BR`). Examples: `MX`, `CO`, `GT`. Used by deployments with location tracking enabled; safe to omit for standard use.
</ParamField>

## Response

<ResponseField name="crop_id" type="string" required>
  The crop ID you submitted, echoed back in the response.
</ResponseField>

<ResponseField name="score" type="integer" required>
  Weighted aptitude score from 0 to 100. Calculated as the dot product of individual factor scores and their weights.
</ResponseField>

<ResponseField name="aptitude" type="string" required>
  Human-readable aptitude tier derived from `score`:

  * `"Alta"` — score ≥ 70
  * `"Media"` — score 45–69
  * `"Baja"` — score \< 45
</ResponseField>

<ResponseField name="recommendation_text" type="string" required>
  Plain-language recommendation summarising the score, highlighting critical or attention-worthy factors, and suggesting management actions where relevant.
</ResponseField>

<ResponseField name="factors" type="array" required>
  List of individual scoring factors that compose the final score.

  <Expandable title="Factor object properties">
    <ResponseField name="name" type="string">
      Factor label (in Spanish). Examples: `"Precipitación anual"`, `"Temperatura media"`, `"Exposición a incendios"`.
    </ResponseField>

    <ResponseField name="value" type="number">
      Observed or computed value for this factor. May be `null` when data is unavailable (e.g. historical yield).
    </ResponseField>

    <ResponseField name="unit" type="string">
      Unit of the value. Examples: `"mm/año"`, `"°C"`, `"m³/m³"`, `"%"`.
    </ResponseField>

    <ResponseField name="score" type="integer">
      Factor score 0–100 before weighting is applied.
    </ResponseField>

    <ResponseField name="weight" type="number">
      Fractional weight of this factor in the final score. Weights across all factors sum to 1.0.

      | Factor                   | Weight |
      | ------------------------ | ------ |
      | Aptitud biofísica (GAEZ) | 0.25   |
      | Precipitación anual      | 0.20   |
      | Temperatura media        | 0.15   |
      | Humedad del suelo        | 0.15   |
      | Exposición a incendios   | 0.10   |
      | pH del suelo             | 0.10   |
      | Rendimiento histórico    | 0.05   |
    </ResponseField>

    <ResponseField name="status" type="string">
      Traffic-light status for this factor: `"ok"` (score ≥ 70), `"warning"` (45–69), or `"risk"` (\< 45).
    </ResponseField>

    <ResponseField name="ideal" type="string">
      Ideal value or range for this crop. Example: `"500–800 mm"`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="season" type="string" required>
  The season value used for this calculation, echoed from the request.
</ResponseField>

<ResponseField name="lat" type="float" required>
  Latitude echoed from the request.
</ResponseField>

<ResponseField name="lon" type="float" required>
  Longitude echoed from the request.
</ResponseField>

<ResponseField name="_cache" type="object">
  Cache metadata describing whether the underlying climate data was served from cache or fetched live.

  <Expandable title="_cache properties">
    <ResponseField name="fresh" type="boolean">
      `true` if data was fetched from the upstream source on this request.
    </ResponseField>

    <ResponseField name="cached_at" type="string">
      ISO 8601 timestamp of when the cached entry was stored.
    </ResponseField>

    <ResponseField name="stale" type="boolean">
      `true` if the cache entry is older than the configured TTL but was served as a fallback.
    </ResponseField>
  </Expandable>
</ResponseField>

## Error codes

| Code  | Description                                                                                   |
| ----- | --------------------------------------------------------------------------------------------- |
| `502` | Upstream error from Open-Meteo or NASA FIRMS. The detail field contains the upstream message. |
| `503` | Open-Meteo rate limit hit. Retry after a short back-off.                                      |

## Example

<RequestExample>
  ```bash cURL theme={null}
  curl "https://api.climatifai.com/agri/advisor?lat=19.4326&lon=-99.1332&crop_id=maiz&season=lluvias&country_iso=MX"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "crop_id": "maiz",
    "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": 712.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.241,
        "unit": "m³/m³",
        "score": 96,
        "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"
      }
    ],
    "season": "lluvias",
    "lat": 19.4326,
    "lon": -99.1332,
    "_cache": {
      "fresh": true,
      "cached_at": "2026-05-18T10:00:00Z",
      "stale": false
    }
  }
  ```
</ResponseExample>