GET /agri/advisor — Crop aptitude score

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

float

required

Center latitude of the location you want to evaluate. Decimal degrees, WGS 84.

float

required

Center longitude of the location you want to evaluate. Decimal degrees, WGS 84.

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.

string

default:"annual"

Season context for the score calculation. Accepted values: lluvias (rainy season), secas (dry season), annual (full-year average).

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

string

required

The crop ID you submitted, echoed back in the response.

integer

required

Weighted aptitude score from 0 to 100. Calculated as the dot product of individual factor scores and their weights.

string

required

Human-readable aptitude tier derived from score:

"Alta" — score ≥ 70
"Media" — score 45–69
"Baja" — score < 45

string

required

Plain-language recommendation summarising the score, highlighting critical or attention-worthy factors, and suggesting management actions where relevant.

array

required

List of individual scoring factors that compose the final score.

Show Factor object properties

string

Factor label (in Spanish). Examples: "Precipitación anual", "Temperatura media", "Exposición a incendios".

number

Observed or computed value for this factor. May be null when data is unavailable (e.g. historical yield).

string

Unit of the value. Examples: "mm/año", "°C", "m³/m³", "%".

integer

Factor score 0–100 before weighting is applied.

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

string

Traffic-light status for this factor: "ok" (score ≥ 70), "warning" (45–69), or "risk" (< 45).

string

Ideal value or range for this crop. Example: "500–800 mm".

string

required

The season value used for this calculation, echoed from the request.

float

required

Latitude echoed from the request.

float

required

Longitude echoed from the request.

object

Cache metadata describing whether the underlying climate data was served from cache or fetched live.

Show _cache properties

boolean

true if data was fetched from the upstream source on this request.

string

ISO 8601 timestamp of when the cached entry was stored.

boolean

true if the cache entry is older than the configured TTL but was served as a fallback.

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

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

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

REST Endpoints

GraphQL

GET /agri/advisor — Crop aptitude score

Endpoint

Parameters

Response

Error codes

Example

​Endpoint

​Parameters

​Response

​Error codes

​Example

Endpoint

Parameters

Response

Error codes

Example