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

# Score crop aptitude for any LATAM location

> Step-by-step guide to scoring a crop's aptitude with the AgroRisk advisor, from choosing coordinates and crop ID to reading the factor breakdown.

The crop advisor endpoint scores how well a given crop is likely to perform at a specific latitude/longitude, based on five years of historical climate data from Open-Meteo (ERA5). The API combines rainfall adequacy, temperature fit, soil moisture, biophysical suitability (GAEZ proxy), and recent fire exposure into a single 0–100 score and an aptitude label.

<Steps>
  <Step title="Choose your location">
    The API uses decimal-degree coordinates in the standard WGS 84 convention:

    * **Latitude** (`lat`): positive = north, negative = south. Range: −90 to 90.
    * **Longitude** (`lon`): positive = east, negative = west. Range: −180 to 180.

    For example, Buenos Aires is `lat=-34.6, lon=-58.4`; Mexico City is `lat=19.4, lon=-99.1`.

    If you do not know the exact coordinates for a region, use the geocode endpoint to search by name:

    ```bash theme={null}
    curl "https://api.climatifai.com/agri/geocode?q=Oaxaca&count=3"
    ```

    The response returns a ranked list of matching places, each with `lat` and `lon` you can pass directly to the advisor.
  </Step>

  <Step title="Choose a crop ID">
    Pass a `crop_id` from the table below. You can use either the Spanish ID (canonical) or its English alias — the API resolves both.

    | `crop_id`  | English alias | Common name      |
    | ---------- | ------------- | ---------------- |
    | `maiz`     | `maize`       | Maize / Corn     |
    | `trigo`    | `wheat`       | Wheat            |
    | `cafe`     | `coffee`      | Coffee (Arabica) |
    | `soya`     | `soybean`     | Soybean          |
    | `vid`      | `vineyard`    | Grapevine        |
    | `frijol`   | `bean`        | Common Bean      |
    | `papa`     | `potato`      | Potato           |
    | `arroz`    | `rice`        | Rice             |
    | `cana`     | `sugarcane`   | Sugarcane        |
    | `tomate`   | `tomato`      | Tomato           |
    | `cebolla`  | `onion`       | Onion            |
    | `ajo`      | `garlic`      | Garlic           |
    | `girasol`  | `sunflower`   | Sunflower        |
    | `sorgo`    | `sorghum`     | Sorghum          |
    | `algodon`  | `cotton`      | Cotton           |
    | `quinua`   | `quinoa`      | Quinoa           |
    | `aguacate` | `avocado`     | Avocado          |

    Passing an unrecognized `crop_id` returns a score of 0 with aptitude `"Desconocida"`.
  </Step>

  <Step title="Choose a season">
    The `season` parameter filters which historical months are used to compute climate averages:

    | Value     | Meaning                                              |
    | --------- | ---------------------------------------------------- |
    | `annual`  | Full 12-month average (default)                      |
    | `lluvias` | Rainy-season months (April–October in most of LATAM) |
    | `secas`   | Dry-season months (November–March)                   |

    For annual crops such as maize or soybean, `annual` is usually the right choice. For crops that are planted specifically in one season, use the matching season value to get a more precise score.
  </Step>

  <Step title="Make the request">
    Send a `GET` request to `/agri/advisor` with your chosen parameters:

    ```bash theme={null}
    curl "https://api.climatifai.com/agri/advisor?lat=-34.6&lon=-58.4&crop_id=maiz&season=annual"
    ```

    All four parameters (`lat`, `lon`, `crop_id`, `season`) are accepted as query string values. `season` defaults to `annual` if omitted.
  </Step>

  <Step title="Interpret the response">
    The response contains a top-level score, an aptitude label, a per-factor breakdown, and a human-readable recommendation.

    ```json theme={null}
    {
      "crop_id": "maiz",
      "crop_name": "Maíz",
      "score": 74,
      "aptitude": "Alta",
      "season": "annual",
      "lat": -34.6,
      "lon": -58.4,
      "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": 17.2,
          "unit": "°C",
          "score": 72,
          "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": 80,
          "unit": "%",
          "score": 80,
          "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": { "stale": false, "source": "upstream" }
    }
    ```

    **Key fields:**

    * **`score`** — Weighted average of all factor scores, 0–100. Higher is better.
    * **`aptitude`** — Summary label: `Alta` (≥ 70), `Media` (45–69), or `Baja` (\< 45).
    * **`factors`** — Array of individual scoring dimensions. Each factor includes:
      * `score` (0–100): how well the observed value fits the crop's ideal range.
      * `weight`: this factor's contribution to the final score (all weights sum to 1.0).
      * `status`: `ok` (score ≥ 70), `warning` (45–69), or `risk` (\< 45).
    * **`recommendation_text`** — Plain-language summary in Spanish, listing any `risk` or `warning` factors.
  </Step>
</Steps>

<Tip>
  To compare two crops at the same location, use the GraphQL `compare` query. It runs both advisor calls in parallel and returns a `winner` field with the higher-scoring `crop_id`:

  ```graphql theme={null}
  query {
    compare(lat: -34.6, lon: -58.4, cropIdA: "maiz", cropIdB: "soya", season: "annual") {
      winner
      cropA { cropId score aptitude }
      cropB { cropId score aptitude }
    }
  }
  ```
</Tip>