Skip to main content

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.

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

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:
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.
2

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_idEnglish aliasCommon name
maizmaizeMaize / Corn
trigowheatWheat
cafecoffeeCoffee (Arabica)
soyasoybeanSoybean
vidvineyardGrapevine
frijolbeanCommon Bean
papapotatoPotato
arrozriceRice
canasugarcaneSugarcane
tomatetomatoTomato
cebollaonionOnion
ajogarlicGarlic
girasolsunflowerSunflower
sorgosorghumSorghum
algodoncottonCotton
quinuaquinoaQuinoa
aguacateavocadoAvocado
Passing an unrecognized crop_id returns a score of 0 with aptitude "Desconocida".
3

Choose a season

The season parameter filters which historical months are used to compute climate averages:
ValueMeaning
annualFull 12-month average (default)
lluviasRainy-season months (April–October in most of LATAM)
secasDry-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.
4

Make the request

Send a GET request to /agri/advisor with your chosen parameters:
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.
5

Interpret the response

The response contains a top-level score, an aptitude label, a per-factor breakdown, and a human-readable recommendation.
{
  "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.
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:
query {
  compare(lat: -34.6, lon: -58.4, cropIdA: "maiz", cropIdB: "soya", season: "annual") {
    winner
    cropA { cropId score aptitude }
    cropB { cropId score aptitude }
  }
}