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

# GET /fires/risk — Aggregated fire risk score

> GET /fires/risk returns a 0–100 fire risk score and Alto/Medio/Bajo label based on NASA FIRMS hotspot density within a configurable radius.

The fire risk endpoint aggregates NASA FIRMS hotspot data from the last five days within a configurable radius around a coordinate and distills it into a single 0–100 risk score. The score is then mapped to a human-readable label — `Alto`, `Medio`, or `Bajo` — so you can quickly triage field locations without parsing raw hotspot arrays. Use this endpoint when you need a single signal to drive alerting logic or to populate a risk dashboard.

## Endpoint

```text theme={null}
GET api.climatifai.com/fires/risk
```

## Parameters

<ParamField query="lat" type="float" required>
  Center latitude of the location to assess in decimal degrees, WGS 84.
</ParamField>

<ParamField query="lon" type="float" required>
  Center longitude of the location to assess in decimal degrees, WGS 84.
</ParamField>

<ParamField query="radius_km" default="100" type="float">
  Search radius around the center point in kilometres. All hotspots detected within this radius are included in the risk calculation.
</ParamField>

## Response

<ResponseField name="lat" type="float" required>
  Center latitude echoed from the request.
</ResponseField>

<ResponseField name="lon" type="float" required>
  Center longitude echoed from the request.
</ResponseField>

<ResponseField name="radius_km" type="float" required>
  Search radius echoed from the request.
</ResponseField>

<ResponseField name="risk_score" type="float" required>
  Aggregated fire risk score on a 0–100 scale. Higher values indicate greater fire activity within the search radius. Computed from the number and intensity of active hotspots detected by VIIRS\_SNPP\_NRT over the last five days.
</ResponseField>

<ResponseField name="risk_label" type="string" required>
  Human-readable risk tier derived from `risk_score`:

  * `"Alto"` — score ≥ 60
  * `"Medio"` — score 30–59
  * `"Bajo"` — score \< 30
</ResponseField>

<ResponseField name="hotspot_count" type="integer" required>
  Number of active fire hotspots detected within the search radius over the last five days.
</ResponseField>

<ResponseField name="_cache" type="object">
  Cache metadata for the underlying NASA FIRMS data.

  <Expandable title="_cache properties">
    <ResponseField name="fresh" type="boolean">
      `true` if data was fetched from NASA FIRMS on this request rather than served from cache.
    </ResponseField>

    <ResponseField name="cached_at" type="string">
      ISO 8601 timestamp of when this cache entry was stored.
    </ResponseField>

    <ResponseField name="stale" type="boolean">
      `true` if a stale cache entry was served as a fallback due to an upstream error.
    </ResponseField>
  </Expandable>
</ResponseField>

## Error codes

| Code  | Description                                                                             |
| ----- | --------------------------------------------------------------------------------------- |
| `502` | Upstream error from NASA FIRMS. The `detail` field contains the original error message. |

## Example

<RequestExample>
  ```bash cURL theme={null}
  curl "https://api.climatifai.com/fires/risk?lat=19.4326&lon=-99.1332&radius_km=150"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "lat": 19.4326,
    "lon": -99.1332,
    "radius_km": 150,
    "risk_score": 42.7,
    "risk_label": "Medio",
    "hotspot_count": 5,
    "_cache": {
      "fresh": true,
      "cached_at": "2026-05-18T11:30:00Z",
      "stale": false
    }
  }
  ```
</ResponseExample>