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

# Climatifai GraphQL query reference

> Complete reference for all Climatifai GraphQL queries — arguments, return types, and copy-paste examples for advisor, climate, fires, alerts, and more.

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.

```graphql theme={null}
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                   |

```bash cURL theme={null}
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.

```graphql theme={null}
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³       |

```bash cURL theme={null}
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.

```graphql theme={null}
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               |

```bash cURL theme={null}
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.

```graphql theme={null}
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          |

```bash cURL theme={null}
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`.

```graphql theme={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`                      |

```bash cURL theme={null}
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.

```graphql theme={null}
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.

```bash cURL theme={null}
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.

```graphql theme={null}
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                 |

```bash cURL theme={null}
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.

```graphql theme={null}
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) |

```bash cURL theme={null}
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 } }"
  }'
```