API Queimadas/INPE¶

O módulo Queimadas fornece acesso aos dados de focos de calor detectados por satelite, disponibilizados pelo INPE (Instituto Nacional de Pesquisas Espaciais) via BDQueimadas.

Funções¶

`focos`¶

Busca focos de calor detectados por satelite no Brasil.

async def focos(
    *,
    ano: int,
    mes: int,
    dia: int | None = None,
    uf: str | None = None,
    bioma: str | None = None,
    satelite: str | None = None,
    as_polars: bool = False,
    return_meta: bool = False,
) -> pd.DataFrame | tuple[pd.DataFrame, MetaInfo]

Parâmetros:

Parâmetro	Tipo	Descrição
`ano`	`int`	Ano (ex: 2024)
`mes`	`int`	Mes (1-12)
`dia`	`int \\| None`	Dia específico (1-31). O INPE só mantém o arquivo diário dos últimos dias: dia mais antigo levanta `SourceUnavailableError` (use o mês inteiro). Se None, busca mes completo
`uf`	`str \\| None`	Filtrar por UF (ex: "MT", "SP"). Case insensitive
`bioma`	`str \\| None`	Filtrar por bioma (ex: "Amazonia", "Cerrado"). Aceita com ou sem acentos; valor desconhecido levanta `ValueError`
`satelite`	`str \\| None`	Filtrar por satelite (ex: "AQUA_M-T", "NOAA-20"), sem diferenciar caixa; sem filtro, vêm os focos de todos os satélites. Satélite que não aparece no arquivo do período levanta `InvalidParameterError` com os publicados, depois do download
`as_polars`	`bool`	Retornar como polars.DataFrame
`return_meta`	`bool`	Se True, retorna tupla (DataFrame, MetaInfo)

Retorno:

DataFrame com colunas: - data: Data do foco (date) - hora_gmt: Horario GMT (str, formato "HH:MM") - lat: Latitude (float) - lon: Longitude (float) - satelite: Nome do satelite detector (str) - municipio: Nome do município (str) - municipio_id: Código IBGE do município (Int64) - estado: Nome do estado (str) - bioma: Bioma canônico (str) — Amazônia, Cerrado, Mata Atlântica, Caatinga, Pampa, Pantanal - numero_dias_sem_chuva: Dias sem precipitação (float) - precipitacao: Precipitação em mm (float) - risco_fogo: Índice de risco de fogo 0-1 (float) - frp: Fire Radiative Power em MW (float); o negativo publicado pela fonte sai nulo, com aviso

As 4 colunas numéricas saem em float64, com NaN onde a fonte publica -999 ou nada. - uf: Sigla da UF (str, 2 caracteres) - cod_municipio: Código IBGE de 7 dígitos, do municipio_id (Int64, nulo fora de município)

Exemplo:

from datetime import date, timedelta

from agrobr import queimadas

# Todos os focos de setembro/2024
df = await queimadas.focos(ano=2024, mes=9)

# Focos de um dia específico (ontem): o INPE só mantém o arquivo diário dos últimos dias
ontem = date.today() - timedelta(days=1)
df = await queimadas.focos(ano=ontem.year, mes=ontem.month, dia=ontem.day)

# Filtrar por UF
df = await queimadas.focos(ano=2024, mes=9, uf="MT")

# Filtrar por bioma
df = await queimadas.focos(ano=2024, mes=9, bioma="Cerrado")

# Filtrar por satelite
df = await queimadas.focos(ano=2024, mes=9, satelite="AQUA_M-T")

# Combinar filtros
df = await queimadas.focos(ano=2024, mes=9, uf="MT", bioma="Amazonia")

# Com metadados de proveniencia
df, meta = await queimadas.focos(ano=2024, mes=9, return_meta=True)
print(meta.source, meta.records_count)

`focos_geo`¶

Mesmos focos de calor de focos, mas com geometria de pontos. Retorna GeoDataFrame com coluna geometry (Point EPSG:4326).

Requer dependencia opcional: pip install agrobr[geo]

async def focos_geo(
    *,
    ano: int,
    mes: int,
    dia: int | None = None,
    uf: str | None = None,
    bioma: str | None = None,
    satelite: str | None = None,
    return_meta: bool = False,
) -> gpd.GeoDataFrame | tuple[gpd.GeoDataFrame, MetaInfo]

Parametros: identicos a focos (sem as_polars).

Retorno:

GeoDataFrame com as mesmas colunas de focos mais:

geometry: Ponto Point EPSG:4326 derivado de lon/lat

Exemplo:

from agrobr import queimadas

gdf = await queimadas.focos_geo(ano=2024, mes=9, uf="MT")

# Cruzamento geoespacial com biomas/municipios
import geopandas as gpd
municipios = gpd.read_file("municipios.geojson")
focos_por_municipio = gpd.sjoin(gdf, municipios)

Satelites Disponíveis¶

Satelite	Descrição
`AQUA_M-T`	AQUA MODIS (referencia)
`AQUA_M-M`	AQUA MODIS (Morning)
`TERRA_M-T`	TERRA MODIS (Tarde)
`TERRA_M-M`	TERRA MODIS (Morning)
`NOAA-20`	NOAA-20 VIIRS
`NOAA-21`	NOAA-21 VIIRS
`GOES-16`	GOES-16 (geoestacionario)
`GOES-19`	GOES-19 (geoestacionario)
`METOP-B`	MetOp-B
`METOP-C`	MetOp-C
`MSG-03`	Meteosat
`NPP-375`	Suomi NPP 375m
`NPP-375D`	Suomi NPP 375m (diurno)

Biomas¶

Bioma	Area Aproximada
Amazonia	4.2M km2
Cerrado	2.0M km2
Mata Atlantica	1.1M km2
Caatinga	844k km2
Pampa	176k km2
Pantanal	150k km2

Versão Síncrona¶

from agrobr.sync import queimadas

df = queimadas.focos(ano=2024, mes=9, uf="MT")
df, meta = queimadas.focos(ano=2024, mes=9, return_meta=True)
gdf = queimadas.focos_geo(ano=2024, mes=9, uf="MT")