firms-client 0.2.0

firms-client is a small, typed, async Python library for NASA FIRMS, the Fire Information for Resource Management System: every active fire seen from space since 2000. It downloads the open per-country archives (no account, no key), queries the near-real-time area API, and does the parsing that tells a vegetation fire from a steelworks.

rows = await fetch_archive(client, VIIRS_SNPP, 2025, "Italy")  # 23,349 detections, no key
fires = select(rows)  # 14,880 vegetation fires

One dependency: httpx.

Contents

• What is FIRMS, in 30 seconds
• What this library does
• Who is it for
• Quick start
• Where downloads are saved
• Not every hotspot is a fire
• How it works
• Recipes
• The traps we already fell into
• API at a glance
• Contributing · Ideas to work on
• Data licence and credits

What is FIRMS, in 30 seconds

Several satellites look at the whole Earth a few times a day with thermal infrared sensors. When a pixel is much hotter than its surroundings, it is reported as a hotspot: a point with a position, a time, a brightness temperature, a fire radiative power (FRP, in MW) and a confidence. NASA collects them in FIRMS, a few hours after the overpass.

flowchart LR
    S["🛰️ MODIS (Terra, Aqua)<br/>🛰️ VIIRS (S-NPP, NOAA-20, NOAA-21)"] --> F["NASA LANCE / FIRMS<br/>hotspot detection"]
    F --> A["📦 Per-country yearly CSVs<br/>open, 2000 →"]
    F --> N["⚡ Area API<br/>1-5 days per query, MAP_KEY"]
    A -->|fetch_archive| C["firms-client<br/>parse · classify · select"]
    N -->|fetch_area| C
    C --> U["Your analysis<br/>fire history · risk models · alerts"]

What people use it for:

• a fire history of a country or region, year by year, for 26 years;
• a wildfire trigger: something is burning in my area right now;
• training data for fire-risk and burnt-area models;
• air-quality and emissions work, from the radiative power of each fire.

What this library does

Who is it for

• Researchers and students in remote sensing, ecology and climate who want FIRMS data in a notebook or pipeline, without the e-mail order form.
• Data engineers who need a repeatable national fire history.
• Civil protection and risk teams who want a wildfire trigger over their area, with industrial sources already filtered out.

It started inside Limen, which uses the archives as the fire history of Italy and the area API as a wildfire trigger, and was extracted so that anyone can use it.

Quick start

1. Install

pip install firms-client

Python 3.12 or newer.

2. Download a country's year, no key needed

import asyncio
from collections import Counter

import httpx

from firms_client import ARCHIVE_PRODUCTS, fetch_archive, select


async def main() -> None:
    async with httpx.AsyncClient(timeout=120) as client:
        for product in ARCHIVE_PRODUCTS:
            rows = await fetch_archive(client, product, 2025, "Italy")
            if rows is None:  # that year is not published (yet)
                continue
            fires = select(rows)  # vegetation fires, nominal confidence or better
            types = dict(sorted(Counter(r.detection_type for r in rows).items()))
            print(product.slug, len(rows), "detections", types, "->", len(fires), "fires")


asyncio.run(main())

modis 5076 detections {0: 3414, 1: 21, 2: 1635, 3: 6} -> 3315 fires
viirs-snpp 23349 detections {0: 17533, 1: 633, 2: 4277, 3: 906} -> 14880 fires

The CSVs are now in ~/.cache/firms-client/: run it again and nothing is downloaded. The country is its English name, as FIRMS writes it (Italy, Greece, United_States…).

3. Or the last days, with a MAP_KEY

The archive runs up to the previous year. For the last days, get a free MAP_KEY (an e-mail address is enough) and ask the area API:

from firms_client import fetch_area, select

ITALY = (6.0, 36.0, 19.0, 47.6)  # west, south, east, north

rows = await fetch_area(client, MAP_KEY, "VIIRS_SNPP_NRT", ITALY, days=3)
fires = select(rows, min_frp_mw=1.0)

days goes from 1 to 5 (the API's limit), on_date=date(2026, 8, 1) moves the window back. The area API is near-real-time and is never cached.

Where downloads are saved

Yearly archives go to the directory you pass (directory= on fetch_archive, fetch_archive_csv and download_archive). If you pass none:

1. FIRMS_DATA_DIR, if set;
2. otherwise ~/.cache/firms-client (or $XDG_CACHE_HOME/firms-client).

~/.cache/firms-client/
├── modis_2025_Italy.csv          400 KB
├── viirs-snpp_2025_Italy.csv     1.8 MB
└── viirs-snpp_2024_Italy.csv     …

flowchart TD
    Q["fetch_archive(client, VIIRS_SNPP, 2025, 'Italy')"] --> E{"viirs-snpp_2025_Italy.csv<br/>in the data directory?"}
    E -->|yes| R["read from disk<br/>no request"]
    E -->|no| G["GET the yearly CSV"]
    G -->|404| N["None<br/>(not cached: it may be published later)"]
    G -->|200| P["stream to …csv.part"]
    P --> V{"is it a hotspot CSV?"}
    V -->|no| X["delete .part<br/>raise FirmsError"]
    V -->|yes| M["rename to .csv"] --> R

A file that exists is whole: downloads are streamed to a .part file and renamed only when complete. To refresh a year, delete its file.

In Docker, point it at a volume so the data survives the container:

services:
  app:
    environment:
      FIRMS_DATA_DIR: /data/firms
    volumes:
      - firms-data:/data/firms
volumes:
  firms-data:

It is the same convention as egms-client (EGMS_DATA_DIR), so one volume can hold both under /data.

Not every hotspot is a fire

A satellite sees heat, not fire. Steelworks, refineries, gas flares, volcanoes and offshore platforms are hot every day of the year, and they come through at high confidence, because they really are hot. FIRMS labels every detection with a type:

On Italy, about a quarter of the VIIRS detections are not vegetation fires, and 98% of those pass a nominal-confidence filter. Without type == 0, the most "burnt" square kilometre in the country over the whole archive is the ILVA steelworks in Taranto, with 3,308 fire-days.

The difference is starkest in winter, when there are few real fires and the factories keep burning:

Two things no filter fixes: crop-residue burning is a real vegetation fire (type 0), and only land cover can set it apart; and FIRMS is presence-only, so no detection does not mean nothing burnt (clouds, smoke and the time of the overpass all hide fires).

All the images above are drawn from the real archives by docs/make_images.py, with this library.

How it works

Two doors in: archives and area API

From a CSV row to a Hotspot

MODIS and VIIRS share one layout, with two differences the parser absorbs: confidence (a percentage for MODIS, a level for VIIRS) and the 4 µm brightness column (brightness vs bright_ti4). Every row becomes a frozen dataclass:

Rows without coordinates, date or a valid time are skipped.

What select() keeps

flowchart TD
    H["Hotspot"] --> T{"vegetation_only and<br/>type is 1, 2 or 3?"}
    T -->|yes| D1["❌ dropped<br/>volcano · industry · offshore"]
    T -->|"no (type 0, or no type)"| C{"confidence"}
    C -->|missing| F
    C -->|"VIIRS level"| L{"≥ min_confidence?<br/>(nominal)"}
    C -->|"MODIS %"| P{"≥ min_confidence_pct?<br/>else mapped: &lt;30 low,<br/>30-79 nominal, 80+ high"}
    L -->|no| D2["❌ dropped"]
    P -->|no| D2
    L -->|yes| F{"min_frp_mw > 0?"}
    P -->|yes| F
    F -->|"no"| K["✅ kept"]
    F -->|"yes: FRP ≥ min"| K
    F -->|"yes: FRP lower or missing"| D3["❌ dropped"]

select(rows, vegetation_only=True, min_confidence="nominal", min_confidence_pct=None, min_frp_mw=0.0):

• a row without type is kept, since it cannot be judged;
• a missing confidence is kept: losing a real fire is worse than keeping a doubtful pixel;
• confidence_level("87") → "high", confidence_level("n") → "nominal": use it to put both instruments on one scale yourself.

What happens on errors

Recipes

The fire history of a country

from firms_client import VIIRS_SNPP, archive_years, fetch_archive, select


async def history(client: httpx.AsyncClient, country: str) -> dict[int, int]:
    """Vegetation fires per year; the first run downloads, the next ones read from disk."""
    per_year = {}
    for year in archive_years(VIIRS_SNPP, until=2025):
        rows = await fetch_archive(client, VIIRS_SNPP, year, country)
        if rows is not None:
            per_year[year] = len(select(rows))
    return per_year

Fire-days per square kilometre

Run it with and without select() to find your country's steelworks:

from collections import defaultdict

days: dict[tuple[float, float], set[date]] = defaultdict(set)
for year in archive_years(VIIRS_SNPP, until=2025):
    for r in await fetch_archive(client, VIIRS_SNPP, year, "Italy") or []:
        days[round(r.latitude, 2), round(r.longitude, 2)].add(r.acq_date)

hottest = sorted(days.items(), key=lambda kv: len(kv[1]), reverse=True)[:5]
for (lat, lon), d in hottest:
    print(f"{lat:.2f}, {lon:.2f}: {len(d)} fire-days")

A monthly chart

With pip install matplotlib:

import matplotlib.pyplot as plt

rows = await fetch_archive(client, VIIRS_SNPP, 2025, "Italy")
fires = [0] * 12
other = [0] * 12
for r in rows:
    (fires if r.is_vegetation_fire is not False else other)[r.acq_date.month - 1] += 1

months = range(1, 13)
plt.bar(months, other, label="industry, volcano, offshore")
plt.bar(months, fires, bottom=other, label="vegetation fire")
plt.legend()
plt.title("VIIRS detections over Italy, 2025")
plt.show()

GeoJSON for QGIS or a web map

import json

features = [
    {
        "type": "Feature",
        "geometry": {"type": "Point", "coordinates": [h.longitude, h.latitude]},
        "properties": {
            "date": h.acq_date.isoformat(),
            "time": f"{h.acq_time:04d}",
            "frp_mw": h.frp_mw,
            "confidence": h.confidence,
            "type": h.detection_type,
        },
    }
    for h in select(rows)
]
Path("fires.geojson").write_text(json.dumps({"type": "FeatureCollection", "features": features}))

A wildfire trigger

async def watch(client: httpx.AsyncClient, map_key: str, bbox: BBox) -> None:
    seen: set[tuple[float, float, date, int]] = set()
    while True:
        for source in ("VIIRS_SNPP_NRT", "VIIRS_NOAA20_NRT", "VIIRS_NOAA21_NRT"):
            for h in select(await fetch_area(client, map_key, source, bbox), min_frp_mw=5.0):
                key = (h.latitude, h.longitude, h.acq_date, h.acq_time)
                if key not in seen:
                    seen.add(key)
                    print(f"🔥 {h.latitude:.3f}, {h.longitude:.3f}  {h.frp_mw} MW  {source}")
        await asyncio.sleep(15 * 60)

Bring your own HTTP

archive_url, archive_filename, area_url, is_hotspot_csv and parse_csv are pure: download with anything, parse with this.

from firms_client import VIIRS_SNPP, archive_url, parse_csv

url = archive_url(VIIRS_SNPP, 2025, "Greece")
rows = parse_csv(requests.get(url, timeout=120).text)

The traps we already fell into

All checked against the live service on 3 November 2026.

API at a glance

Every async function takes your httpx.AsyncClient: timeouts, proxies, retries and pooling stay yours.

Contributing

Issues and pull requests are welcome; see CONTRIBUTING.md.

git clone https://github.com/agent-engineering-studio/firms-client
cd firms-client
uv sync
make check   # ruff, mypy --strict, pytest with coverage: the same gate as CI

Tests never touch the network: they run against small fixtures cut from the 2025 Italian archives.

Ideas to work on

• 🌍 More archives: per-country files for other products, if FIRMS publishes them; a list of the country names FIRMS accepts.
• 🗺️ Area API over history: the *_SP sources and date ranges longer than 5 days, split into windows.
• 🔁 Retries for 429/5xx, as in egms-client, opt-in.
• 🖥️ A command line: firms archive Italy 2025, firms area --bbox ….
• 🧭 Clustering neighbouring hotspots into fire events.
• 📓 Notebooks: a national fire history, a burnt-area comparison.

If you use firms-client in a project or a paper, open an issue and tell us: we will link it here.

Data licence and credits

FIRMS data are provided by NASA LANCE / FIRMS and are free to use; please acknowledge "NASA FIRMS" in anything you publish, for example:

We acknowledge the use of data and imagery from LANCE FIRMS operated by NASA's Earth Science Data and Information System (ESDIS) with funding provided by NASA Headquarters.

The test fixtures are a few rows of the 2025 Italian archives, and the images in this README are drawn from the full 2025 archives.

Extracted from Limen. See also egms-client for the ground motion of Europe from Sentinel-1.

License

Code: Apache-2.0.