Climatifai GraphQL query reference

This page documents every query available in the Climatifai GraphQL schema. Each entry shows the full argument list, the return type and its fields, and a working curl example you can copy and run immediately. All queries are read-only — the schema exposes no mutations.

advisor

Returns an agricultural aptitude score for a specific crop at a given location. The score (0–100) is derived from a weighted combination of climate, soil, and fire exposure factors.

query {
  advisor(lat: Float!, lon: Float!, cropId: String!, season: String) {
    cropId
    score
    aptitude
    recommendationText
    season
    lat
    lon
    factors {
      label
      score
      weight
      status
      description
    }
  }
}

Arguments

Argument	Type	Required	Default	Description
`lat`	Float	Yes	—	Center latitude in decimal degrees
`lon`	Float	Yes	—	Center longitude in decimal degrees
`cropId`	String	Yes	—	Canonical crop identifier (e.g. `"maiz"`, `"cafe"`)
`season`	String	No	`"annual"`	`"lluvias"`, `"secas"`, or `"annual"`

Return fields — AdvisorResult

Field	Type	Description
`cropId`	String	Crop identifier echoed from the request
`score`	Float	Weighted aptitude score 0–100
`aptitude`	String	`"Alta"` (≥ 70), `"Media"` (45–69), `"Baja"` (< 45)
`recommendationText`	String	Plain-language recommendation
`season`	String	Season echoed from the request
`lat`	Float	Latitude echoed from the request
`lon`	Float	Longitude echoed from the request
`factors`	[AdvisorFactor]	Individual scoring factors
`factors.label`	String	Factor name
`factors.score`	Float	Factor score 0–100
`factors.weight`	Float	Fractional weight in the final score
`factors.status`	String	`"ok"`, `"warning"`, or `"risk"`
`factors.description`	String	Optional description of the factor

cURL

curl --request POST \
  --url "https://api.climatifai.com/graphql" \
  --header "Content-Type: application/json" \
  --data '{
    "query": "{ advisor(lat: 19.4326, lon: -99.1332, cropId: \"maiz\", season: \"lluvias\") { score aptitude recommendationText factors { label score weight status } } }"
  }'

climate

Returns historical monthly climate data and CMIP6 climate projections for a location. Use this query to understand long-term trends and future scenarios without making separate REST calls.

query {
  climate(lat: Float!, lon: Float!, from: Int, to: Int, scenario: String) {
    lat
    lon
    scenario
    historical {
      year
      month
      tempC
      precipMm
      soilMoisture
    }
    projected {
      year
      month
      tempC
      precipMm
      soilMoisture
    }
  }
}

Arguments

Argument	Type	Required	Default	Description
`lat`	Float	Yes	—	Latitude in decimal degrees
`lon`	Float	Yes	—	Longitude in decimal degrees
`from`	Int	No	`1991`	Start year for the historical series
`to`	Int	No	`2020`	End year for the historical series
`scenario`	String	No	`"SSP3-7.0"`	CMIP6 emissions scenario for projections

Return fields — ClimateResult

Field	Type	Description
`lat`	Float	Latitude echoed from the request
`lon`	Float	Longitude echoed from the request
`scenario`	String	Emissions scenario used for projections
`historical`	[ClimateMonth]	Monthly historical climate records
`projected`	[ClimateMonth]	Monthly projected climate records
`*.year`	Int	Calendar year
`*.month`	Int	Month (1–12)
`*.tempC`	Float	Mean temperature in °C
`*.precipMm`	Float	Total precipitation in mm
`*.soilMoisture`	Float	Volumetric soil moisture in m³/m³

cURL

curl --request POST \
  --url "https://api.climatifai.com/graphql" \
  --header "Content-Type: application/json" \
  --data '{
    "query": "{ climate(lat: -34.0, lon: -61.0, from: 2000, to: 2020, scenario: \"SSP3-7.0\") { scenario historical { year month tempC precipMm } projected { year month tempC precipMm } } }"
  }'

hotspots

Returns active NASA FIRMS fire hotspot detections within a radius around a location. Each record includes brightness, fire radiative power, satellite, and confidence level.

query {
  hotspots(lat: Float!, lon: Float!, radiusKm: Float, days: Int, source: String) {
    lat
    lon
    radiusKm
    days
    count
    hotspots {
      lat
      lon
      brightness
      frp
      acqDate
      acqTime
      satellite
      confidence
    }
  }
}

Arguments

Argument	Type	Required	Default	Description
`lat`	Float	Yes	—	Center latitude
`lon`	Float	Yes	—	Center longitude
`radiusKm`	Float	No	`100`	Search radius in kilometres
`days`	Int	No	`5`	Look-back period in days (1–5)
`source`	String	No	`"VIIRS_SNPP_NRT"`	FIRMS data source

Return fields — HotspotsResult

Field	Type	Description
`lat`	Float	Center latitude echoed from the request
`lon`	Float	Center longitude echoed from the request
`radiusKm`	Float	Search radius echoed from the request
`days`	Int	Look-back period echoed from the request
`count`	Int	Total number of hotspots detected
`hotspots`	[Hotspot]	Array of individual fire detections
`hotspots.lat`	Float	Hotspot centroid latitude
`hotspots.lon`	Float	Hotspot centroid longitude
`hotspots.brightness`	Float	Brightness temperature in Kelvin
`hotspots.frp`	Float	Fire Radiative Power in megawatts
`hotspots.acqDate`	String	Acquisition date (`YYYY-MM-DD`)
`hotspots.acqTime`	String	Acquisition time (`HHMM` UTC)
`hotspots.satellite`	String	Satellite name code
`hotspots.confidence`	String	Detection confidence level

cURL

curl --request POST \
  --url "https://api.climatifai.com/graphql" \
  --header "Content-Type: application/json" \
  --data '{
    "query": "{ hotspots(lat: -22.0, lon: -60.0, radiusKm: 150, days: 3) { count hotspots { lat lon brightness frp acqDate confidence } } }"
  }'

fireRisk

Returns an aggregated 0–100 fire risk score and a human-readable label for a location. This query is equivalent to the REST GET /fires/risk endpoint but lets you combine it with other data in a single request.

query {
  fireRisk(lat: Float!, lon: Float!, radiusKm: Float) {
    lat
    lon
    radiusKm
    riskScore
    riskLabel
    hotspotCount
  }
}

Arguments

Argument	Type	Required	Default	Description
`lat`	Float	Yes	—	Center latitude
`lon`	Float	Yes	—	Center longitude
`radiusKm`	Float	No	`100`	Search radius in kilometres

Return fields — FireRiskResult

Field	Type	Description
`lat`	Float	Latitude echoed from the request
`lon`	Float	Longitude echoed from the request
`radiusKm`	Float	Search radius echoed from the request
`riskScore`	Float	Aggregated fire risk score 0–100
`riskLabel`	String	`"Alto"` (≥ 60), `"Medio"` (30–59), `"Bajo"` (< 30)
`hotspotCount`	Int	Number of active hotspots within the radius

cURL

curl --request POST \
  --url "https://api.climatifai.com/graphql" \
  --header "Content-Type: application/json" \
  --data '{
    "query": "{ fireRisk(lat: 19.4326, lon: -99.1332, radiusKm: 100) { riskScore riskLabel hotspotCount } }"
  }'

compare

Evaluates two crops at the same location and season in parallel and returns their individual advisor results alongside a winner field indicating which crop scored higher. If both crops score equally, winner is null.

query {
  compare(
    lat: Float!
    lon: Float!
    cropIdA: String!
    cropIdB: String!
    season: String
  ) {
    lat
    lon
    season
    winner
    cropA {
      cropId
      score
      aptitude
      recommendationText
    }
    cropB {
      cropId
      score
      aptitude
      recommendationText
    }
  }
}

Arguments

Argument	Type	Required	Default	Description
`lat`	Float	Yes	—	Latitude of the location to evaluate
`lon`	Float	Yes	—	Longitude of the location to evaluate
`cropIdA`	String	Yes	—	First crop’s canonical identifier
`cropIdB`	String	Yes	—	Second crop’s canonical identifier
`season`	String	No	`"annual"`	`"lluvias"`, `"secas"`, or `"annual"`

Return fields — CompareResult

Field	Type	Description
`lat`	Float	Latitude echoed from the request
`lon`	Float	Longitude echoed from the request
`season`	String	Season echoed from the request
`winner`	String	`cropId` of the higher-scoring crop, or `null` if tied
`cropA`	AdvisorResult	Full advisor result for `cropIdA`
`cropB`	AdvisorResult	Full advisor result for `cropIdB`

cURL

curl --request POST \
  --url "https://api.climatifai.com/graphql" \
  --header "Content-Type: application/json" \
  --data '{
    "query": "{ compare(lat: 20.5, lon: -101.0, cropIdA: \"maiz\", cropIdB: \"sorgo\", season: \"secas\") { winner cropA { score aptitude } cropB { score aptitude } } }"
  }'

alerts

Returns live agroclimatic alerts for eight key agricultural zones across LATAM (excluding Brazil). Alerts are generated in real time from NASA FIRMS fire data and Open-Meteo forecasts, and cover fire activity, heat waves, drought, and heavy rain events.

query {
  alerts {
    generatedAt
    zonesChecked
    alerts {
      title
      severity
      message
      generatedAt
      region
      alertType
    }
  }
}

Arguments This query takes no arguments. Return fields — AlertsResult

Field	Type	Description
`generatedAt`	String	ISO 8601 timestamp when this batch of alerts was generated
`zonesChecked`	Int	Number of LATAM zones evaluated (always 8)
`alerts`	[Alert]	List of active alerts sorted by severity (high first)
`alerts.title`	String	Short alert title
`alerts.severity`	String	`"alta"`, `"media"`, or `"baja"`
`alerts.message`	String	Full alert description with actionable guidance
`alerts.generatedAt`	String	ISO 8601 timestamp for this individual alert
`alerts.region`	String	Name of the LATAM zone the alert applies to
`alerts.alertType`	String	`"fire"`, `"heat"`, `"drought"`, or `"rain"`

Monitored zones: Orinoquía (Colombia/Venezuela), Chaco (Paraguay/Argentina), Bajío (México), Centroamérica, Llanos Orientales (Colombia), Pampa Húmeda (Argentina), Valle Central (Chile), Sierra Peruana.

cURL

curl --request POST \
  --url "https://api.climatifai.com/graphql" \
  --header "Content-Type: application/json" \
  --data '{
    "query": "{ alerts { generatedAt zonesChecked alerts { title severity message region alertType } } }"
  }'

geocode

Searches for place names within LATAM and returns matching locations with coordinates, country, and elevation metadata. Use this query to resolve a user-supplied location string into lat/lon coordinates before calling other queries.

query {
  geocode(q: String!, count: Int) {
    results {
      name
      lat
      lon
      country
      admin1
      elevation
      population
    }
  }
}

Arguments

Argument	Type	Required	Default	Description
`q`	String	Yes	—	Place name search query
`count`	Int	No	`5`	Maximum number of results to return

Return fields — GeocodeResult

Field	Type	Description
`results`	[GeocodePlace]	Array of matching places
`results.name`	String	Place name
`results.lat`	Float	Latitude
`results.lon`	Float	Longitude
`results.country`	String	Country name
`results.admin1`	String	First-level administrative region
`results.elevation`	Float	Elevation in metres above sea level
`results.population`	Int	Population estimate

cURL

curl --request POST \
  --url "https://api.climatifai.com/graphql" \
  --header "Content-Type: application/json" \
  --data '{
    "query": "{ geocode(q: \"Bajío México\", count: 3) { results { name lat lon country admin1 } } }"
  }'

ragContext

Performs semantic search over the agroclimatic document corpus using ClimateBERT embeddings and Qdrant vector search. Returns the most relevant text passages along with their source identifiers and similarity scores.

query {
  ragContext(query: String!, limit: Int) {
    text
    source
    score
  }
}

Arguments

Argument	Type	Required	Default	Description
`query`	String	Yes	—	Natural-language search query
`limit`	Int	No	`3`	Maximum number of passages to return

Return fields — [RagPassage]

Field	Type	Description
`text`	String	Extracted passage text
`source`	String	Source document identifier
`score`	Float	Cosine similarity score (higher is more relevant)

cURL

curl --request POST \
  --url "https://api.climatifai.com/graphql" \
  --header "Content-Type: application/json" \
  --data '{
    "query": "{ ragContext(query: \"drought tolerance maize LATAM\", limit: 3) { text source score } }"
  }'

REST Endpoints

GraphQL

Documentation Index

​advisor

​climate

​hotspots

​fireRisk

​compare

​alerts

​geocode

​ragContext

advisor

climate

hotspots

fireRisk

compare

alerts

geocode

ragContext