API IBGE¶

O módulo IBGE fornece acesso aos dados do Sistema IBGE de Recuperação Automática (SIDRA).

Funções¶

`pam`¶

Obtém dados da Produção Agrícola Municipal.

async def pam(
    produto: str,
    ano: int | list[int] | None = None,
    uf: str | None = None,
    nivel: str = 'uf',
    variaveis: list[str] | None = None,
    as_polars: bool = False,
) -> pd.DataFrame | pl.DataFrame

Parâmetros:

Parâmetro	Tipo	Descrição
`produto`	`str`	Código do produto (ex: 'soja', 'milho')
`ano`	`int \\| list[int] \\| None`	Ano(s). Default: último disponível
`uf`	`str \\| None`	Filtrar por UF (ex: 'MT')
`nivel`	`str`	Nível: 'brasil', 'uf', 'municipio'
`variaveis`	`list[str] \\| None`	Variáveis específicas
`as_polars`	`bool`	Retornar como polars.DataFrame

Variáveis disponíveis:

Código	Variável
`area_plantada`	Área plantada (hectares)
`area_colhida`	Área colhida (hectares)
`producao`	Quantidade produzida (toneladas)
`rendimento`	Rendimento médio (kg/ha)

Exemplo:

from agrobr import ibge

# PAM por UF
df = await ibge.pam('soja', ano=2023, nivel='uf')

# Múltiplos anos
df = await ibge.pam('soja', ano=[2020, 2021, 2022, 2023])

# Por município (filtrar UF para reduzir volume)
df = await ibge.pam('soja', ano=2023, nivel='municipio', uf='MT')

# Variáveis específicas
df = await ibge.pam('soja', ano=2023, variaveis=['producao', 'area_plantada'])

`lspa`¶

Obtém dados do Levantamento Sistemático da Produção Agrícola.

async def lspa(
    produto: str,
    ano: int | None = None,
    mes: int | None = None,
    uf: str | None = None,
    as_polars: bool = False,
) -> pd.DataFrame | pl.DataFrame

Parâmetros:

Parâmetro	Tipo	Descrição
`produto`	`str`	Código do produto
`ano`	`int \\| None`	Ano. Default: atual
`mes`	`int \\| None`	Mês (1-12). Default: último
`uf`	`str \\| None`	Filtrar por UF
`as_polars`	`bool`	Retornar como polars.DataFrame

Produtos LSPA:

Código	Produto
`soja`	Soja
`milho_1`	Milho 1ª safra
`milho_2`	Milho 2ª safra
`arroz`	Arroz
`feijao_1`	Feijão 1ª safra
`feijao_2`	Feijão 2ª safra
`feijao_3`	Feijão 3ª safra
`trigo`	Trigo
`algodao`	Algodão herbáceo
`amendoim_1`	Amendoim 1ª safra
`amendoim_2`	Amendoim 2ª safra
`batata_1`	Batata-inglesa 1ª safra
`batata_2`	Batata-inglesa 2ª safra

Aliases genéricos:

Nomes genéricos expandem automaticamente para sub-safras e retornam um DataFrame concatenado:

Alias	Expande para
`milho`	`milho_1` + `milho_2`
`feijao`	`feijao_1` + `feijao_2` + `feijao_3`
`amendoim`	`amendoim_1` + `amendoim_2`
`batata`	`batata_1` + `batata_2`

Exemplo:

from agrobr import ibge

# LSPA mensal
df = await ibge.lspa('soja', ano=2024, mes=6)

# Milho 2ª safra
df = await ibge.lspa('milho_2', ano=2024)

# Alias genérico — retorna milho_1 + milho_2 concatenados
df = await ibge.lspa('milho', ano=2024)

# Por UF
df = await ibge.lspa('soja', ano=2024, uf='MT')

`produtos_pam`¶

Lista produtos disponíveis na PAM.

async def produtos_pam() -> list[str]

`produtos_lspa`¶

Lista produtos disponíveis no LSPA.

async def produtos_lspa() -> list[str]

`ppm`¶

Obtém dados da Pesquisa da Pecuária Municipal.

async def ppm(
    especie: str,
    ano: int | list[int] | None = None,
    uf: str | None = None,
    nivel: str = 'uf',
    as_polars: bool = False,
) -> pd.DataFrame | pl.DataFrame

Parâmetros:

Parâmetro	Tipo	Descrição
`especie`	`str`	Espécie ou produto (ex: 'bovino', 'leite')
`ano`	`int \\| list[int] \\| None`	Ano(s). Default: último disponível
`uf`	`str \\| None`	Filtrar por UF (ex: 'MT')
`nivel`	`str`	Nível: 'brasil', 'uf', 'municipio'
`as_polars`	`bool`	Retornar como polars.DataFrame

Espécies disponíveis (rebanhos):

Código	Espécie
`bovino`	Bovino
`bubalino`	Bubalino
`equino`	Equino
`suino_total`	Suíno (total)
`suino_matrizes`	Suíno matrizes
`caprino`	Caprino
`ovino`	Ovino
`galinaceos_total`	Galináceos (total)
`galinhas_poedeiras`	Galinhas poedeiras
`codornas`	Codornas

Produtos de origem animal:

Código	Produto	Unidade
`leite`	Leite	mil litros
`ovos_galinha`	Ovos de galinha	mil dúzias
`ovos_codorna`	Ovos de codorna	mil dúzias
`mel`	Mel de abelha	kg
`casulos`	Casulos bicho-da-seda	kg
`la`	Lã	kg

Exemplo:

from agrobr import ibge

# Rebanho bovino por UF
df = await ibge.ppm('bovino', ano=2023, nivel='uf')

# Produção de leite por município em MG
df = await ibge.ppm('leite', ano=2023, nivel='municipio', uf='MG')

# Série histórica
df = await ibge.ppm('bovino', ano=[2019, 2020, 2021, 2022, 2023])

# Com metadados
df, meta = await ibge.ppm('bovino', ano=2023, return_meta=True)

`especies_ppm`¶

Lista espécies e produtos disponíveis na PPM.

async def especies_ppm() -> list[str]

`abate`¶

Obtém dados da Pesquisa Trimestral do Abate de Animais.

async def abate(
    especie: str,
    trimestre: str | None = None,
    uf: str | None = None,
    as_polars: bool = False,
) -> pd.DataFrame | pl.DataFrame

Parâmetros:

Parâmetro	Tipo	Descrição
`especie`	`str`	Espécie: 'bovino', 'suino', 'frango'
`trimestre`	`str \\| None`	Trimestre YYYYQQ (ex: '202303'). Default: último disponível
`uf`	`str \\| None`	Filtrar por UF (ex: 'PR')
`as_polars`	`bool`	Retornar como polars.DataFrame

Espécies disponíveis:

Código	Espécie	Tabela SIDRA
`bovino`	Bovino	1092
`suino`	Suíno	1093
`frango`	Frango	1094

Variáveis retornadas:

Variável	Descrição	Unidade
`animais_abatidos`	Quantidade de animais abatidos	cabeças
`peso_carcacas`	Peso total das carcaças	kg

Exemplo:

from agrobr import ibge

# Abate bovino por UF
df = await ibge.abate('bovino', trimestre='202303')

# Abate de frango no Paraná
df = await ibge.abate('frango', trimestre='202303', uf='PR')

# Abate de suínos — Brasil
df = await ibge.abate('suino', trimestre='202304')

# Com metadados
df, meta = await ibge.abate('bovino', trimestre='202303', return_meta=True)

`especies_abate`¶

Lista espécies disponíveis no Abate Trimestral.

async def especies_abate() -> list[str]

`censo_agro`¶

Obtém dados do Censo Agropecuário (1995, 2006 e 2017).

async def censo_agro(
    tema: str,
    ano: int | str | None = None,
    uf: str | None = None,
    nivel: str = 'uf',
    as_polars: bool = False,
) -> pd.DataFrame | pl.DataFrame

Parâmetros:

Parâmetro	Tipo	Descrição
`tema`	`str`	Tema do censo (ver tabela abaixo)
`ano`	`int \\| str \\| None`	Ano censal (1995, 2006 ou 2017). Default: todos os anos disponíveis
`uf`	`str \\| None`	Filtrar por UF (ex: 'MT')
`nivel`	`str`	Nível: 'brasil', 'uf', 'municipio'
`as_polars`	`bool`	Retornar como polars.DataFrame

Temas disponíveis:

Código	Tema	Tabela 1995	Tabela 2006	Tabela 2017
`efetivo_rebanho`	Efetivo de rebanho	323	—	6907
`uso_terra`	Uso da terra	316/311	—	6881
`lavoura_temporaria`	Lavoura temporária	497/492/503	—	6957
`lavoura_permanente`	Lavoura permanente	509/504/510	—	6956
`preparo_solo`	Preparo do solo	—	791	6855
`adubacao`	Adubação	—	1249	6848
`calagem`	Calagem	—	1245	6849
`agrotoxicos`	Uso de agrotóxicos	—	1459	6851
`praticas_agricolas`	Práticas agrícolas	—	837	8561
`irrigacao`	Irrigação	—	855	6857

Variáveis retornadas por tema (temas originais):

Tema	Variável	Unidade
`efetivo_rebanho`	`estabelecimentos`	unidades
`efetivo_rebanho`	`cabecas`	cabeças
`uso_terra`	`estabelecimentos`	unidades
`uso_terra`	`area`	hectares
`lavoura_temporaria`	`estabelecimentos`	unidades
`lavoura_temporaria`	`producao`	varia
`lavoura_temporaria`	`area_colhida`	hectares
`lavoura_permanente`	`estabelecimentos`	unidades
`lavoura_permanente`	`producao`	varia
`lavoura_permanente`	`area_colhida`	hectares

Categorias dos novos temas (exemplos):

Tema	Categorias (exemplos)
`preparo_solo`	Cultivo convencional, Cultivo mínimo, Plantio direto na palha
`adubacao`	Química, Orgânica, Adubação verde
`calagem`	Fez aplicação, Não fez aplicação
`agrotoxicos`	Utilizou, Não utilizou
`praticas_agricolas`	Plantio em nível, Rotação de culturas, Pousio
`irrigacao`	Gotejamento, Pivô central, Inundação, Aspersão

Exemplo:

from agrobr import ibge

# Efetivo de rebanho por UF (2017)
df = await ibge.censo_agro('efetivo_rebanho')

# Uso da terra em Mato Grosso
df = await ibge.censo_agro('uso_terra', uf='MT')

# Lavoura temporária por município
df = await ibge.censo_agro('lavoura_temporaria', nivel='municipio', uf='PR')

# Preparo do solo — ambos os anos (2006 + 2017)
df = await ibge.censo_agro('preparo_solo')

# Irrigação apenas 2017
df = await ibge.censo_agro('irrigacao', ano=2017)

# Adubação em 2006, filtrado por UF
df = await ibge.censo_agro('adubacao', ano=2006, uf='SP')

# Com metadados
df, meta = await ibge.censo_agro('efetivo_rebanho', return_meta=True)

`temas_censo_agro`¶

Lista temas disponíveis no Censo Agropecuário.

async def temas_censo_agro() -> list[str]

`censo_agro_legado`¶

Obtém dados do Censo Agropecuário 1995/96 — 6 temas legados via FTP (XLS).

async def censo_agro_legado(
    tema: str,
    uf: str | None = None,
    nivel: str = 'uf',
    as_polars: bool = False,
) -> pd.DataFrame | pl.DataFrame

Parâmetros:

Parâmetro	Tipo	Descrição
`tema`	`str`	Tema legado (ver tabela abaixo)
`uf`	`str \\| None`	Filtrar por UF (ex: 'SP')
`nivel`	`str`	Nível: 'brasil', 'uf', 'municipio'
`as_polars`	`bool`	Retornar como polars.DataFrame

Temas disponíveis:

Código	Tema
`tecnologia`	Tecnologia (assistência técnica, irrigação, adubos, etc.)
`pessoal_ocupado`	Pessoal ocupado (total, familiar, permanentes, temporários)
`maquinas`	Máquinas e equipamentos (tratores por faixa de CV)
`producao_animal`	Produção animal (leite, lã, ovos)
`valor_producao`	Valor da produção (vegetal, animal, subtipos)
`financeiro`	Dados financeiros (investimentos, financiamentos, despesas, receitas)

Exemplo:

from agrobr import ibge

# Tecnologia por mesorregião
df = await ibge.censo_agro_legado('tecnologia')

# Pessoal ocupado em São Paulo
df = await ibge.censo_agro_legado('pessoal_ocupado', uf='SP')

# Máquinas — nível município
df = await ibge.censo_agro_legado('maquinas', nivel='municipio')

# Com metadados
df, meta = await ibge.censo_agro_legado('tecnologia', return_meta=True)

`temas_censo_agro_legado`¶

Lista temas disponíveis no Censo Agropecuário Legado (FTP).

async def temas_censo_agro_legado() -> list[str]

`censo_agro_historico`¶

Obtém dados da série histórica do Censo Agropecuário (1920-2006, nível UF máximo).

async def censo_agro_historico(
    tema: str,
    ano: int | list[int] | None = None,
    uf: str | None = None,
    nivel: str = 'uf',
    as_polars: bool = False,
) -> pd.DataFrame | pl.DataFrame

Parâmetros:

Parâmetro	Tipo	Descrição
`tema`	`str`	Tema da série histórica (ver tabela abaixo)
`ano`	`int \\| list[int] \\| None`	Ano(s) censal(ais). Default: todos os disponíveis
`uf`	`str \\| None`	Filtrar por UF (ex: 'SP'). Só aplicado em nivel='uf'
`nivel`	`str`	Nível: 'brasil', 'regiao', 'uf' (municipal NÃO disponível)
`as_polars`	`bool`	Retornar como polars.DataFrame

Temas disponíveis:

Código	Tema	Tabela SIDRA	Períodos
`estabelecimentos_area`	Estabelecimentos e área por grupo de área	263	1920-2006 (10 censos)
`uso_terra`	Área por utilização das terras	264	1970-2006 (6 censos)
`pessoal_tratores`	Pessoal ocupado e tratores	265	1970-2006 (6 censos)
`condicao_produtor`	Estabelecimentos por condição do produtor	280	1920-2006 (10 censos)
`efetivo_animais`	Efetivo de animais por espécie	281	1970-2006 (6 censos)
`producao_animal`	Produção animal por tipo	282	1920-2006 (10 censos)
`producao_vegetal`	Produção vegetal e área colhida	283	1920-2006 (10 censos)
`lavoura_permanente`	Quantidade produzida — lavouras permanentes	1730	1940-2006 (9 censos)
`lavoura_temporaria`	Quantidade produzida — lavouras temporárias	1731	1940-2006 (9 censos)

Exemplo:

from agrobr import ibge

# Estabelecimentos e área, Brasil, 1985
df = await ibge.censo_agro_historico('estabelecimentos_area', ano=1985, nivel='brasil')

# Efetivo de animais, todas as UFs, todos os censos
df = await ibge.censo_agro_historico('efetivo_animais')

# Pessoal e tratores em São Paulo, 1980 e 1985
df = await ibge.censo_agro_historico('pessoal_tratores', ano=[1980, 1985], uf='SP')

# Produção vegetal, nível região
df = await ibge.censo_agro_historico('producao_vegetal', nivel='regiao')

# Com metadados
df, meta = await ibge.censo_agro_historico('uso_terra', ano=1985, return_meta=True)

`temas_censo_agro_historico`¶

Lista temas disponíveis na série histórica do Censo Agropecuário.

async def temas_censo_agro_historico() -> list[str]

CLI¶

# Todos os dados de estabelecimentos/área por UF
agrobr ibge censo-historico estabelecimentos_area

# Ano específico, formato CSV
agrobr ibge censo-historico uso_terra --ano 1985 --formato csv

# Múltiplos anos, nível Brasil
agrobr ibge censo-historico efetivo_animais --ano 1970,1985,2006 --nivel brasil

# Filtrar por UF
agrobr ibge censo-historico pessoal_tratores --ano 1985 --uf SP

# Listar temas disponíveis
agrobr ibge temas-historico

`ufs`¶

Lista UFs disponíveis.

async def ufs() -> list[str]

Diferenças PAM vs LSPA vs PPM vs Abate vs Censo Agro vs Série Histórica¶

Aspecto	PAM	LSPA	PPM	Abate	Censo Agro	Censo Agro Legado	Série Histórica
Frequência	Anual	Mensal	Anual	Trimestral	Decenial	Única (1995/96)	Decenial
Granularidade	Até município	Até UF	Até município	Brasil + UF	Até município	Até município	Brasil/Região/UF
Tipo	Consolidados	Estimativas	Consolidados	Consolidados	Censitários	Censitários (FTP)	Censitários
Disponibilidade	T+1 ano	T+1 mês	T+1 ano	T+2 meses	Pós-censo	Estático	Estático
Escopo	Lavouras	Lavouras	Pecuária	Abate	Estrutura agro	6 temas legados	9 temas (1920-2006)

Tabelas SIDRA Utilizadas¶

Tabela	Descrição
5457	PAM - Nova série (2018+)
6588	LSPA - Estimativas mensais
1612	PAM - Lavouras temporárias (histórico)
3939	PPM - Efetivo de rebanhos
74	PPM - Produção de origem animal
1092	Abate - Bovinos
1093	Abate - Suínos
1094	Abate - Frangos
323	Censo Agro 1995 - Efetivo de rebanho
316 / 311	Censo Agro 1995 - Uso da terra
497 / 492 / 503	Censo Agro 1995 - Lavoura temporária
509 / 504 / 510	Censo Agro 1995 - Lavoura permanente
6907	Censo Agro 2017 - Efetivo de rebanho
6881	Censo Agro 2017 - Uso da terra
6957	Censo Agro 2017 - Lavoura temporária
6956	Censo Agro 2017 - Lavoura permanente
791 / 6855	Censo Agro 2006/2017 - Preparo do solo
1249 / 6848	Censo Agro 2006/2017 - Adubação
1245 / 6849	Censo Agro 2006/2017 - Calagem
1459 / 6851	Censo Agro 2006/2017 - Agrotóxicos
837 / 8561	Censo Agro 2006/2017 - Práticas agrícolas
855 / 6857	Censo Agro 2006/2017 - Irrigação
263	Série Histórica - Estabelecimentos e área
264	Série Histórica - Uso da terra
265	Série Histórica - Pessoal e tratores
280	Série Histórica - Condição do produtor
281	Série Histórica - Efetivo de animais
282	Série Histórica - Produção animal
283	Série Histórica - Produção vegetal
1730	Série Histórica - Lavoura permanente
1731	Série Histórica - Lavoura temporária

Versão Síncrona¶

from agrobr.sync import ibge

df = ibge.pam('soja', ano=2023)
df = ibge.lspa('milho_1', ano=2024, mes=6)
df = ibge.ppm('bovino', ano=2023)
df = ibge.abate('bovino', trimestre='202303')
df = ibge.censo_agro('efetivo_rebanho')
df = ibge.censo_agro('preparo_solo', ano=2017)
df = ibge.censo_agro_legado('tecnologia')
df = ibge.censo_agro_legado('pessoal_ocupado', uf='SP')

Notas¶

Consultas por município geram grande volume de dados
Recomenda-se filtrar por UF quando usar nível município
LSPA é atualizado mensalmente pelo IBGE
PAM é consolidada anualmente após colheita
PPM é consolidada anualmente (setembro), série desde 1974
Abate Trimestral disponível desde 1997, atualizado a cada trimestre (T+2 meses)
Censo Agropecuário: 10 temas, dados de 1995, 2006 e/ou 2017 conforme disponibilidade. Referência 2017: out/2016 a set/2017. Cache 30 dias
Censo Agropecuário Legado: 6 temas FTP (tecnologia, pessoal_ocupado, maquinas, producao_animal, valor_producao, financeiro). Ano fixo 1995. Cache 90 dias
Série Histórica: 9 temas, 1920-2006, até UF (municipal NÃO disponível). Unidades mistas por categoria (Aves=Mil cabeças, etc). Cache 30 dias

API IBGE¶

Funções¶

pam¶

lspa¶

produtos_pam¶

produtos_lspa¶

ppm¶

especies_ppm¶

abate¶

especies_abate¶

censo_agro¶

temas_censo_agro¶

censo_agro_legado¶

temas_censo_agro_legado¶

censo_agro_historico¶

temas_censo_agro_historico¶

CLI¶

ufs¶

Diferenças PAM vs LSPA vs PPM vs Abate vs Censo Agro vs Série Histórica¶

Tabelas SIDRA Utilizadas¶

Versão Síncrona¶

Notas¶

`pam`¶

`lspa`¶

`produtos_pam`¶

`produtos_lspa`¶

`ppm`¶

`especies_ppm`¶

`abate`¶

`especies_abate`¶

`censo_agro`¶

`temas_censo_agro`¶

`censo_agro_legado`¶

`temas_censo_agro_legado`¶

`censo_agro_historico`¶

`temas_censo_agro_historico`¶

`ufs`¶