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

# Fire risk: hotspots and risk scoring

> Learn how AgroRisk fetches NASA FIRMS satellite fire detections and converts hotspot density and intensity into an actionable 0–100 risk score.

The fire risk endpoints give you real-time visibility into active fires near any agricultural location in LATAM. Raw hotspot detections from NASA satellites are available through `/fires/hotspots`, and a pre-computed 0–100 risk score aggregated from those detections is available through `/fires/risk`. Both endpoints feed the fire and flood exposure factor used in crop aptitude scoring.

## Data source

Fire data comes from NASA FIRMS (Fire Information for Resource Management System) via the Area API. FIRMS aggregates active fire detections from multiple satellites and delivers near-real-time (NRT) records typically within 3 hours of the satellite overpass.

### Satellite sources

Control which satellite's data is queried with the `source` parameter:

| Value              | Satellite              | Notes                                        |
| ------------------ | ---------------------- | -------------------------------------------- |
| `VIIRS_SNPP_NRT`   | Suomi NPP / VIIRS      | Default — 375 m resolution, high sensitivity |
| `MODIS_NRT`        | Terra and Aqua / MODIS | 1 km resolution, longer record               |
| `VIIRS_NOAA20_NRT` | NOAA-20 / VIIRS        | Same sensor as Suomi NPP, independent orbit  |

<Tip>
  `VIIRS_SNPP_NRT` is the recommended default for agricultural monitoring because its 375 m pixel resolution detects smaller fires that MODIS may miss in fragmented landscapes.
</Tip>

## Hotspot fields

Each hotspot in the `/fires/hotspots` response represents a single satellite fire detection pixel:

| Field        | Type           | Description                                          |
| ------------ | -------------- | ---------------------------------------------------- |
| `lat`        | float          | Hotspot centroid latitude                            |
| `lon`        | float          | Hotspot centroid longitude                           |
| `brightness` | float \| null  | Brightness temperature (K) from channel Ti4          |
| `frp`        | float \| null  | Fire Radiative Power (MW) — proxy for fire intensity |
| `acq_date`   | string \| null | Acquisition date (`YYYY-MM-DD`)                      |
| `acq_time`   | string \| null | Acquisition time (UTC, `HHMM`)                       |
| `satellite`  | string \| null | Satellite identifier                                 |
| `confidence` | string \| null | Detection confidence (`low`, `nominal`, `high`)      |

## Risk score formula

The `/fires/risk` endpoint computes a single score from 0 to 100 using hotspot density, confidence weighting, and average Fire Radiative Power:

1. **Density component** — hotspot count divided by the search area (π × radius²) in km², scaled by 1000, then multiplied by 20.
2. **High-confidence component** — proportion of hotspots rated `high` or `nominal` confidence, multiplied by 30.
3. **FRP component** — average FRP in MW divided by 5, capped at 50.

These three components are summed and clamped to the 0–100 range:

```
score = min(100, density × 20 + (high_conf_ratio × 30) + min(avg_frp / 5, 50))
```

A location with zero hotspots always returns a score of 0. A dense cluster of high-confidence, high-FRP hotspots produces a score near 100.

### Risk labels

| Label   | Score range | Interpretation                                            |
| ------- | ----------- | --------------------------------------------------------- |
| `Alto`  | ≥ 60        | Significant active fire activity; high crop and soil risk |
| `Medio` | 30–59       | Moderate fire presence; monitor and prepare contingency   |
| `Bajo`  | \< 30       | Low fire activity in the area                             |

<Warning>
  A `Bajo` or `Medio` label reflects the situation at query time based on the last 5 days of satellite passes. Fire conditions can change rapidly. Do not rely solely on this score for emergency response decisions.
</Warning>

## Temporal window

The FIRMS Area API supports a look-back window of 1 to 5 days. Pass the `days` parameter to `/fires/hotspots` to control the window. Values outside the 1–5 range are automatically clamped. The `/fires/risk` endpoint always uses the maximum 5-day window to ensure the score reflects recent cumulative fire activity.

## Caching

Fire hotspot data is cached for **15 minutes**. Because fire conditions are dynamic, the cache window is intentionally short. The `_cache` field in the response reports whether data came from the cache or a fresh FIRMS fetch:

```json theme={null}
"_cache": { "hit": true, "stale": false, "age_sec": 342 }
```

## Sample response

The following is a representative response from `GET /fires/risk?lat=-22.0&lon=-60.0&radius_km=150`:

```json theme={null}
{
  "lat": -22.0,
  "lon": -60.0,
  "radius_km": 150.0,
  "risk_score": 47,
  "risk_label": "Medio",
  "hotspot_count": 18,
  "_cache": {
    "hit": false,
    "stale": false,
    "age_sec": 0
  }
}
```

And a representative `/fires/hotspots` entry for one detection:

```json theme={null}
{
  "lat": -22.143,
  "lon": -59.871,
  "brightness": 331.4,
  "frp": 12.6,
  "acq_date": "2026-05-17",
  "acq_time": "0412",
  "satellite": "N",
  "confidence": "nominal"
}
```

<Note>
  If no `FIRMS_API_KEY` environment variable is set, the API returns an empty hotspot list and a risk score of 0. Register for a free NASA Earthdata API key at [earthdata.nasa.gov](https://earthdata.nasa.gov) to enable live data.
</Note>