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

GET api.climatifai.com/agri/advisor

​
Parameters

​
lat
float
required
Center latitude of the location you want to evaluate. Decimal degrees, WGS 84.
​
lon
float
required
Center longitude of the location you want to evaluate. Decimal degrees, WGS 84.
​
crop_id
string
required
Identifier for the crop to score. The following canonical IDs are supported:
Canonical IDCrop (ES)Crop (EN)
maizMaízMaize
trigoTrigoWheat
cafeCaféCoffee
soyaSoyaSoybean
vidVidGrapevine
frijolFrijolCommon Bean
papaPapaPotato
arrozArrozRice
canaCaña de azúcarSugarcane
tomateTomateTomato
cebollaCebollaOnion
ajoAjoGarlic
girasolGirasolSunflower
sorgoSorgoSorghum
algodonAlgodónCotton
quinuaQuinuaQuinoa
aguacateAguacateAvocado
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.
​
season
string
default:"annual"
Season context for the score calculation. Accepted values: lluvias (rainy season), secas (dry season), annual (full-year average).
​
country_iso
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.

​
Response

​
crop_id
string
required
The crop ID you submitted, echoed back in the response.
​
score
integer
required
Weighted aptitude score from 0 to 100. Calculated as the dot product of individual factor scores and their weights.
​
aptitude
string
required
Human-readable aptitude tier derived from score:
  • "Alta" — score ≥ 70
  • "Media" — score 45–69
  • "Baja" — score < 45
​
recommendation_text
string
required
Plain-language recommendation summarising the score, highlighting critical or attention-worthy factors, and suggesting management actions where relevant.
​
factors
array
required
List of individual scoring factors that compose the final score.
​
season
string
required
The season value used for this calculation, echoed from the request.
​
lat
float
required
Latitude echoed from the request.
​
lon
float
required
Longitude echoed from the request.
​
_cache
object
Cache metadata describing whether the underlying climate data was served from cache or fetched live.

​
Error codes

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

​
Example

curl "https://api.climatifai.com/agri/advisor?lat=19.4326&lon=-99.1332&crop_id=maiz&season=lluvias&country_iso=MX"

{
  "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
  }
}