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

# Detect and assess fire risk near your location

> Query NASA FIRMS fire hotspots and get an aggregated risk score for any LATAM coordinate, with control over radius, lookback days, and satellite source.

The fire monitoring endpoints pull active hotspot data from NASA FIRMS (Fire Information for Resource Management System) and aggregate it into a location-level risk score. You can query raw hotspots to see individual fire detections or call the risk endpoint to get a single 0–100 score suitable for alerts and dashboards.

<Steps>
  <Step title="Query active hotspots">
    Send a `GET` request to `/fires/hotspots` with a center coordinate and search radius. The API returns all active fire detections within that circle for the requested number of past days.

    ```bash theme={null}
    curl "https://api.climatifai.com/fires/hotspots?lat=-22.0&lon=-60.0&radius_km=100&days=5"
    ```

    Sample response:

    ```json theme={null}
    {
      "lat": -22.0,
      "lon": -60.0,
      "radius_km": 100,
      "days": 5,
      "count": 14,
      "hotspots": [
        {
          "lat": -21.83,
          "lon": -59.74,
          "brightness": 342.6,
          "frp": 18.4,
          "acq_date": "2026-05-17",
          "acq_time": "0145",
          "satellite": "N",
          "confidence": "high",
          "source": "VIIRS_SNPP_NRT"
        },
        {
          "lat": -22.41,
          "lon": -60.31,
          "brightness": 315.2,
          "frp": 9.1,
          "acq_date": "2026-05-16",
          "acq_time": "0318",
          "satellite": "N",
          "confidence": "nominal",
          "source": "VIIRS_SNPP_NRT"
        }
      ],
      "_cache": { "stale": false, "source": "upstream" }
    }
    ```

    Each hotspot object includes:

    | Field                   | Description                                            |
    | ----------------------- | ------------------------------------------------------ |
    | `lat` / `lon`           | Detected fire location                                 |
    | `brightness`            | Brightness temperature (K) from the satellite sensor   |
    | `frp`                   | Fire radiative power (MW) — a proxy for fire intensity |
    | `acq_date` / `acq_time` | UTC acquisition date and time (HHMM)                   |
    | `satellite`             | Satellite identifier (e.g., `N` for Suomi NPP)         |
    | `confidence`            | Detection confidence: `low`, `nominal`, or `high`      |
  </Step>

  <Step title="Get the aggregated risk score">
    The `/fires/risk` endpoint calls the same FIRMS data source and converts the hotspot count into a normalised 0–100 risk score.

    ```bash theme={null}
    curl "https://api.climatifai.com/fires/risk?lat=-22.0&lon=-60.0&radius_km=100"
    ```

    ```json theme={null}
    {
      "lat": -22.0,
      "lon": -60.0,
      "radius_km": 100,
      "risk_score": 72,
      "risk_label": "Alto",
      "hotspot_count": 14,
      "_cache": { "stale": false, "source": "upstream" }
    }
    ```

    | Field           | Description                                                         |
    | --------------- | ------------------------------------------------------------------- |
    | `risk_score`    | 0–100. Computed as `max(0, 100 − hotspot_count × 10)`, then capped. |
    | `risk_label`    | `Alto` (score ≥ 60), `Medio` (30–59), or `Bajo` (\< 30)             |
    | `hotspot_count` | Number of hotspots found within `radius_km` over the last 5 days    |

    The risk endpoint always uses a 5-day lookback and the `VIIRS_SNPP_NRT` source. Use `/fires/hotspots` directly if you need different parameters.
  </Step>

  <Step title="Adjust the search radius">
    The `radius_km` parameter (default `100`) defines the circular search area around your coordinate.

    | Radius           | Best for                                             | Tradeoff                                                     |
    | ---------------- | ---------------------------------------------------- | ------------------------------------------------------------ |
    | 25–50 km         | Field-level monitoring; single farm or plantation    | May miss fires that affect air quality or regional logistics |
    | 100 km (default) | Zone-level agricultural risk; most use cases         | Balances precision with regional context                     |
    | 150–200 km       | Regional policy dashboards; broad watershed analysis | Increases hotspot count, which can dilute localised signals  |

    A smaller radius gives you a sharper signal for a specific property but raises the chance of missing a nearby fire that still poses a risk through smoke, heat, or wind-driven spread. For crop insurance or index-based products, 100 km is a reasonable starting radius.
  </Step>

  <Step title="Choose a days lookback">
    The `days` parameter accepts integers from 1 to 5 (default `5`). It controls how far back the FIRMS query looks for detections.

    | `days`        | Use case                                                |
    | ------------- | ------------------------------------------------------- |
    | `1`           | Real-time alerting; maximum freshness, minimum coverage |
    | `3`           | Daily operational monitoring                            |
    | `5` (default) | Weekly risk aggregation; maximum coverage               |

    A single-day window gives you the most recent picture but can undercount fires that were active yesterday and have since spread. A 5-day window smooths out satellite revisit gaps — VIIRS has a roughly 12-hour revisit time at the equator, so a 1-day window may miss detections that fell between passes.
  </Step>

  <Step title="Switch satellite source">
    The `source` parameter (default `VIIRS_SNPP_NRT`) selects the NASA FIRMS data product:

    | Value              | Sensor              | Notes                                                  |
    | ------------------ | ------------------- | ------------------------------------------------------ |
    | `VIIRS_SNPP_NRT`   | VIIRS on Suomi NPP  | Default. 375 m resolution, near-real-time.             |
    | `VIIRS_NOAA20_NRT` | VIIRS on NOAA-20    | Same sensor on a newer satellite; complementary orbit. |
    | `MODIS_NRT`        | MODIS on Terra/Aqua | 1 km resolution; broader spatial coverage per pass.    |

    For the highest detection density, you can query `VIIRS_SNPP_NRT` and `VIIRS_NOAA20_NRT` separately and combine the results. MODIS is useful when you need a longer continuous archive or if VIIRS data is temporarily unavailable.

    ```bash theme={null}
    curl "https://api.climatifai.com/fires/hotspots?lat=-22.0&lon=-60.0&radius_km=100&days=5&source=VIIRS_NOAA20_NRT"
    ```
  </Step>
</Steps>

<Warning>
  NASA FIRMS data is cached by the AgroRisk API for up to 15 minutes. Hotspot counts and timestamps in the response may lag real-time satellite passes by up to 15 minutes. For immediate emergency response, consult the FIRMS web viewer directly.
</Warning>

<Tip>
  To monitor all eight key LATAM agricultural zones at once without making eight separate API calls, use the GraphQL `alerts` query. It runs fire checks in parallel across all zones and returns only the zones with active alerts, sorted by severity:

  ```graphql theme={null}
  query {
    alerts {
      generatedAt
      zonesChecked
      alerts {
        region
        alertType
        severity
        title
        message
      }
    }
  }
  ```

  Filter the result to `alertType: "fire"` to focus on fire events only.
</Tip>