> ## 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/hotspots — Active fire hotspots

> Retrieve active fire hotspots near a location from NASA FIRMS, with configurable search radius, look-back period, and satellite data source.

The fire hotspots endpoint queries NASA FIRMS (Fire Information for Resource Management System) for active fire detections within a circular area around a point of interest. Each hotspot record includes the satellite brightness, fire radiative power (FRP), acquisition time, and confidence level. You can use this endpoint to assess current fire activity near a field before planting or as an input to a broader risk assessment workflow.

## Endpoint

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

## Parameters

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

<ParamField query="lon" type="float" required>
  Center longitude of the search area 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 response.
</ParamField>

<ParamField query="days" default="5" type="integer">
  Number of days to look back from the current date. Must be between `1` and `5`. This constraint is imposed by the FIRMS Area API.
</ParamField>

<ParamField query="source" default="VIIRS_SNPP_NRT" type="string">
  NASA FIRMS data source to query. Accepted values:

  | Value              | Description                                          |
  | ------------------ | ---------------------------------------------------- |
  | `VIIRS_SNPP_NRT`   | VIIRS sensor on Suomi NPP satellite (near-real-time) |
  | `MODIS_NRT`        | MODIS sensor (near-real-time, lower resolution)      |
  | `VIIRS_NOAA20_NRT` | VIIRS sensor on NOAA-20 satellite (near-real-time)   |
</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="days" type="integer" required>
  Look-back period in days echoed from the request.
</ResponseField>

<ResponseField name="count" type="integer" required>
  Total number of hotspots detected within the search area.
</ResponseField>

<ResponseField name="hotspots" type="array" required>
  Array of individual fire hotspot detections. Empty when no fires are detected.

  <Expandable title="Hotspot object properties">
    <ResponseField name="lat" type="float">
      Latitude of the hotspot centroid.
    </ResponseField>

    <ResponseField name="lon" type="float">
      Longitude of the hotspot centroid.
    </ResponseField>

    <ResponseField name="brightness" type="float">
      Brightness temperature at the fire pixel in Kelvin (VIIRS) or channel 21/22 brightness (MODIS).
    </ResponseField>

    <ResponseField name="frp" type="float">
      Fire Radiative Power in megawatts. Higher values indicate more intense fires.
    </ResponseField>

    <ResponseField name="acq_date" type="string">
      Acquisition date in `YYYY-MM-DD` format.
    </ResponseField>

    <ResponseField name="acq_time" type="string">
      Acquisition time in `HHMM` format (UTC).
    </ResponseField>

    <ResponseField name="satellite" type="string">
      Satellite name. Example: `"N"` (NOAA-20), `"S"` (Suomi NPP), `"T"` (Terra), `"A"` (Aqua).
    </ResponseField>

    <ResponseField name="confidence" type="string">
      Detection confidence. For VIIRS: `"low"`, `"nominal"`, or `"high"`. For MODIS: a numeric percentage string.
    </ResponseField>

    <ResponseField name="source" type="string">
      FIRMS data source that produced this detection, matching the `source` query parameter.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="_cache" type="object">
  Cache metadata for the FIRMS data used in this response.

  <Expandable title="_cache properties">
    <ResponseField name="fresh" type="boolean">
      `true` if data was fetched from NASA FIRMS on this request.
    </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/hotspots?lat=19.4326&lon=-99.1332&radius_km=150&days=3&source=VIIRS_SNPP_NRT"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "lat": 19.4326,
    "lon": -99.1332,
    "radius_km": 150,
    "days": 3,
    "count": 2,
    "hotspots": [
      {
        "lat": 19.21,
        "lon": -99.47,
        "brightness": 331.2,
        "frp": 8.4,
        "acq_date": "2026-05-17",
        "acq_time": "0648",
        "satellite": "S",
        "confidence": "nominal",
        "source": "VIIRS_SNPP_NRT"
      },
      {
        "lat": 19.58,
        "lon": -98.91,
        "brightness": 305.7,
        "frp": 3.1,
        "acq_date": "2026-05-16",
        "acq_time": "1812",
        "satellite": "N",
        "confidence": "low",
        "source": "VIIRS_SNPP_NRT"
      }
    ],
    "_cache": {
      "fresh": true,
      "cached_at": "2026-05-18T10:15:00Z",
      "stale": false
    }
  }
  ```
</ResponseExample>