agrobr 1.0.5

Dados agrícolas brasileiros em uma linha de código

agrobr

Dados agrícolas brasileiros em uma linha de código

Infraestrutura Python para dados agrícolas brasileiros com camada semântica sobre 38 fontes públicas: CEPEA, CONAB, IBGE, NASA POWER, BCB/SICOR, ComexStat, ANDA, ABIOVE, USDA PSD, IMEA, DERAL, INMET, Notícias Agrícolas, Queimadas/INPE, Desmatamento PRODES/DETER, MapBiomas, CONAB Progresso, B3 Futuros Agro, CONAB CEASA/PROHORT, UN Comtrade, ANTAQ, ANP Diesel, MAPA PSR, ANTT Pedágio, SICAR, ZARC, Agrofit/MAPA (Defensivos), FUNAI, ICMBio, INCRA, IBAMA, MapBiomas Alerta, Lista Suja, ANA/SNIRH, SFB, RNC/CultivarWeb, EMBRAPA Solos e Fundação Rio Verde.

v1.0.5 — 6000+ testes, 92% cobertura, 38/38 fontes com golden tests, retry centralizado em 38/38 clients.

Demo

Instalação

pip install agrobr

Com extras opcionais:

pip install agrobr[pdf]             # pdfplumber para ANDA, Lista Suja, Rio Verde
pip install agrobr[polars]          # Suporte a Polars
pip install agrobr[browser]         # Playwright (opcional, para fontes com JS)
pip install agrobr[bigquery]        # Base dos Dados (fallback BCB/SICOR)
pip install agrobr[geo]             # GeoPandas (geometria PRODES + DETER + SICAR + FUNAI + ICMBio + INCRA + IBAMA + Queimadas + MapBiomas Alerta + ANA + SFB + EMBRAPA Solos)
pip install agrobr[all]             # Tudo incluído

Docker

docker build -t agrobr .
docker run -it --rm agrobr

>>> from agrobr.sync import cepea
>>> df = cepea.indicador('soja', inicio='2024-01-01')

# CLI
docker run --rm agrobr agrobr cepea indicador boi

# Persistir cache entre execuções
docker run -it --rm -v agrobr-cache:/home/agrobr/.agrobr agrobr

# Com extras adicionais (EXTRAS substitui o default "browser,pdf")
docker build --build-arg EXTRAS="browser,pdf,polars" -t agrobr:extras .

# Rodar script local
docker run --rm -v "$(pwd)":/work agrobr python /work/analise.py

A imagem default inclui Playwright + Chromium (CONAB) e pdfplumber (ANDA). Veja o guia Docker para extras adicionais.

Uso Rápido

CEPEA - Indicadores de Preços

import asyncio
from agrobr import cepea

async def main():
    # Série histórica de soja
    df = await cepea.indicador('soja', inicio='2024-01-01')
    print(df.head())

    # Último valor disponível
    ultimo = await cepea.ultimo('soja')
    print(f"Soja: R$ {ultimo.valor}/sc em {ultimo.data}")

    # Produtos disponíveis
    print(await cepea.produtos())  # ['soja', 'milho', 'boi_gordo', 'cafe', ...]

asyncio.run(main())

CONAB - Safras e Balanço

from agrobr import conab

async def main():
    # Dados de safra por UF
    df = await conab.safras('soja', safra='2024/25')
    print(df[['uf', 'area_plantada', 'producao', 'produtividade']])

    # Balanço oferta/demanda
    balanco = await conab.balanco('soja')
    print(balanco)

    # Total Brasil
    brasil = await conab.brasil_total()
    print(brasil)

IBGE - PAM, LSPA, PPM, Abate, PEVS, Leite, PIB e Censo Agro

from agrobr import ibge

async def main():
    # PAM - Produção Agrícola Municipal (anual)
    df = await ibge.pam('soja', ano=2023, nivel='uf')
    print(df[['localidade', 'area_plantada', 'producao']])

    # LSPA - Levantamento Sistemático (mensal)
    df = await ibge.lspa('soja', ano=2024, mes=6)
    print(df)

    # PPM - Pesquisa da Pecuária Municipal (anual)
    df = await ibge.ppm('bovino', ano=2023, nivel='uf')
    print(df[['localidade', 'especie', 'valor', 'unidade']])

    # Produção de origem animal
    df = await ibge.ppm('leite', ano=2023)

    # Abate Trimestral — bovino, suíno, frango
    df = await ibge.abate('bovino', trimestre='202303')
    df = await ibge.abate('frango', trimestre='202303', uf='PR')

    # PAM por município (filtrando UF para reduzir volume)
    df = await ibge.pam('cafe', ano=2023, nivel='municipio', uf='PA')

    # Censo Agropecuário 1995/2006/2017 — 10 temas
    df = await ibge.censo_agro('efetivo_rebanho')
    df = await ibge.censo_agro('uso_terra', uf='MT')
    df = await ibge.censo_agro('lavoura_temporaria', nivel='municipio', uf='PR')

    # Manejo de solo e irrigação (2006 + 2017)
    df = await ibge.censo_agro('preparo_solo', ano=2017, uf='SP')
    df = await ibge.censo_agro('irrigacao')  # ambos os anos
    df = await ibge.censo_agro('adubacao', ano=2006)

    # Censo Agropecuário 1995/96 — temas legados (FTP)
    df = await ibge.censo_agro_legado('tecnologia')
    df = await ibge.censo_agro_legado('pessoal_ocupado', uf='SP')

    # Censo Agropecuário — série histórica 1920-2006 (9 temas, até UF)
    df = await ibge.censo_agro_historico('estabelecimentos_area')
    df = await ibge.censo_agro_historico('efetivo_animais', uf='SP')
    df = await ibge.censo_agro_historico('uso_terra', nivel='brasil')

    # Censo Agropecuário 1985 — dados municipais (53 temas, 22 UFs, OCR de PDFs)
    df = await ibge.censo_agro_municipal_1985('propriedade_terras', uf='SP')
    df = await ibge.censo_agro_municipal_1985('bovinos', nivel='municipio')

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

    # PEVS — Silvicultura (eucalipto, pinus, carvão)
    df = await ibge.silvicultura('madeira_tora', ano=2023)
    df = await ibge.silvicultura('eucalipto', variavel='area')  # área plantada

    # PEVS — Extração vegetal (açaí, castanha, erva-mate)
    df = await ibge.extracao_vegetal('acai', ano=2023, nivel='uf')

    # Leite trimestral (aquisição + industrialização + preço)
    df = await ibge.leite_trimestral(trimestre='202303', uf='MG')

    # PIB Agropecuário trimestral
    df = await ibge.pib_agro(trimestre='202501', setor='agropecuaria')

Datasets - Camada Semântica

Peça o que quer, fonte é detalhe interno:

from agrobr import datasets

async def main():
    # Preço diário (CEPEA com fallback automático)
    df = await datasets.preco_diario("soja")

    # Produção anual (IBGE PAM → CONAB)
    df = await datasets.producao_anual("soja", ano=2023)

    # Estimativa de safra corrente (CONAB → IBGE LSPA)
    df = await datasets.estimativa_safra("soja", safra="2024/25")

    # Balanço oferta/demanda (CONAB)
    df = await datasets.balanco("soja")

    # Crédito rural (BCB/SICOR com fallback BigQuery)
    df = await datasets.credito_rural("soja", safra="2024/25")

    # Exportações (ComexStat → ABIOVE)
    df = await datasets.exportacao("soja", ano=2024)

    # Fertilizantes (ANDA)
    df = await datasets.fertilizante(ano=2024, uf="MT")

    # Custos de produção (CONAB)
    df = await datasets.custo_producao("soja", uf="MT", safra="2024/25")

    # Com metadados de proveniência
    df, meta = await datasets.preco_diario("soja", return_meta=True)
    print(meta.source, meta.contract_version)

    # Pecuária municipal (IBGE PPM)
    df = await datasets.pecuaria_municipal("bovino", ano=2023)

    # Censo Agropecuário 1995/2006/2017 (IBGE Censo Agro — 10 temas)
    df = await datasets.censo_agropecuario("efetivo_rebanho")
    df = await datasets.censo_agropecuario("preparo_solo")

    # Cadastro Ambiental Rural (SICAR)
    df = await datasets.cadastro_rural("DF")
    df = await datasets.cadastro_rural("MT", municipio="Sorriso", status="AT")

    # SICAR com geometria (requer pip install agrobr[geo])
    gdf = await agrobr.alt.sicar.imoveis_geo("DF")

    # Silvicultura (IBGE PEVS)
    df = await datasets.silvicultura("madeira_tora", ano=2023)

    # Extrativismo vegetal (IBGE PEVS)
    df = await datasets.extrativismo_vegetal("acai", ano=2023)

    # Leite industrial (IBGE Leite Trimestral)
    df = await datasets.leite_industrial(trimestre="202303")

    # Série histórica de safras (CONAB — 32 culturas)
    df = await datasets.serie_historica_safra("soja", inicio=2020, fim=2024)

    # Preços de atacado (CONAB CEASA/PROHORT)
    df = await datasets.preco_atacado("TOMATE")

    # Seguro rural (MAPA PSR — apólices e sinistros)
    df = await datasets.seguro_rural(tipo="apolices", uf="MT", ano=2023)
    df = await datasets.seguro_rural(tipo="sinistros", evento="SECA")

    # Clima (INMET → NASA POWER)
    df = await datasets.clima(uf="SP", ano=2024)
    df = await datasets.clima(estacao="A301", inicio="2024-01-01", fim="2024-12-31")

    # Futuros agrícolas B3 (ajustes, histórico, posições)
    df = await datasets.futuros_agricolas("boi", data="2025-03-05")
    df = await datasets.futuros_agricolas("boi", tipo="historico", inicio="2025-01-01", fim="2025-03-05")
    df = await datasets.futuros_agricolas("boi", tipo="posicoes", data="2025-03-05")

    # Listar datasets disponíveis
    print(datasets.list_datasets())
    # ['abate_trimestral', 'balanco', 'cadastro_rural', 'censo_agropecuario',
    #  'censo_agropecuario_historico', 'censo_agropecuario_legado',
    #  'censo_agropecuario_municipal_1985', 'clima', 'comercio_internacional',
    #  'condicao_lavouras', 'credito_rural', 'custo_producao', 'desmatamento',
    #  'estimativa_safra', 'exportacao', 'extrativismo_vegetal', 'fertilizante',
    #  'futuros_agricolas', 'importacao', 'leite_industrial',
    #  'movimentacao_portuaria', 'oferta_demanda_global', 'pecuaria_municipal',
    #  'pib_agro', 'preco_atacado', 'preco_diario', 'producao_anual',
    #  'progresso_safra', 'queimadas', 'seguro_rural', 'serie_historica_safra',
    #  'silvicultura', 'uso_do_solo', 'zoneamento_agricola']

Modo Determinístico e Snapshots (Reprodutibilidade)

Snapshots capturam dados locais em parquet para reprodutibilidade total — ideal para papers, auditorias e pipelines CI.

from agrobr import datasets
from agrobr.snapshots import create_snapshot, list_snapshots, delete_snapshot

# Criar snapshot (salva dados atuais em ~/.agrobr/snapshots/)
info = await create_snapshot("2025-Q4")                        # nome customizado
info = await create_snapshot(sources=["cepea", "conab"])       # fontes específicas

# Listar e remover
for s in list_snapshots():
    print(s.name, s.file_count, f"{s.size_bytes/1024/1024:.1f} MB")
delete_snapshot("2025-Q4")

# Modo determinístico — consultas usam apenas cache local, sem rede
async with datasets.deterministic("2025-12-31"):
    df = await datasets.preco_diario("soja")

Via CLI:

agrobr snapshot create 2025-Q4 --sources cepea,conab,ibge
agrobr snapshot list
agrobr snapshot list --json
agrobr snapshot use 2025-Q4       # ativa modo determinístico
agrobr snapshot delete 2025-Q4

Novas Fontes v0.7.0+

from agrobr import nasa_power, bcb, comexstat, anda

async def main():
    # NASA POWER — climatologia por ponto ou UF (v0.7.1)
    df = await nasa_power.clima_ponto(-12.6, -56.1, "2024-01-01", "2024-12-31")
    df = await nasa_power.clima_uf("MT", ano=2024)

    # BCB/SICOR — crédito rural
    df = await bcb.credito_rural(produto="soja", safra="2024/25")

    # BCB/SICOR — filtrar por programa
    df = await bcb.credito_rural(produto="soja", safra="2024/25", programa="Pronamp")

    # BCB/SICOR — agregar por programa
    df = await bcb.credito_rural(produto="soja", safra="2024/25", agregacao="programa")

    # ComexStat — exportações e importações mensais
    df = await comexstat.exportacao("soja", ano=2024, agregacao="mensal")
    df = await comexstat.importacao("soja", ano=2024, agregacao="mensal")

    # ANDA — entregas de fertilizantes (requer pip install agrobr[pdf])
    df = await anda.entregas(ano=2024, uf="MT")

    # CONAB — custos de produção
    from agrobr import conab
    df = await conab.custo_producao(cultura="soja", uf="MT", safra="2024/25")

Novas Fontes v0.8.0

from agrobr import abiove, usda, imea, deral, conab

async def main():
    # ABIOVE — exportação do complexo soja
    df = await abiove.exportacao(ano=2024, produto="grao")

    # USDA PSD — estimativas internacionais (requer API key gratuita)
    df = await usda.psd("soja", country="BR", market_year=2024)

    # IMEA — cotações e indicadores Mato Grosso
    df = await imea.cotacoes("soja", safra="24/25")

    # DERAL — condição das lavouras Paraná
    df = await deral.condicao_lavouras("soja")

    # CONAB — série histórica de safras (2010+)
    df = await conab.serie_historica("soja", inicio=2020, fim=2025, uf="MT")

INMET — Token de Autenticação

A API de dados observacionais do INMET requer token. Configure via variável de ambiente:

export AGROBR_INMET_TOKEN="seu-token-aqui"

Sem o token, requisições de dados levantam SourceUnavailableError (HTTP 403). A listagem de estações funciona sem token. Para dados climáticos sem token, use NASA POWER como alternativa.

Queimadas/INPE — Focos de Calor (v0.10.0)

from agrobr import queimadas

async def main():
    # Focos de calor em setembro/2024
    df = await queimadas.focos(ano=2024, mes=9)

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

    # Dia especifico
    df = await queimadas.focos(ano=2024, mes=9, dia=15)

    # Com metadados
    df, meta = await queimadas.focos(ano=2024, mes=9, return_meta=True)

Desmatamento PRODES/DETER (v0.10.0)

from agrobr import desmatamento

async def main():
    # PRODES — desmatamento anual consolidado (Cerrado)
    df = await desmatamento.prodes(bioma="Cerrado", ano=2022, uf="MT")

    # PRODES com geometria (requer pip install agrobr[geo])
    gdf = await desmatamento.prodes_geo(bioma="Cerrado", ano=2022, uf="MT")

    # DETER — alertas em tempo real (Amazônia)
    df = await desmatamento.deter(
        bioma="Amazônia", uf="PA",
        data_inicio="2024-01-01", data_fim="2024-06-30",
    )

    # Filtrar por classe de alerta
    df = await desmatamento.deter(bioma="Amazônia", classe="DESMATAMENTO_CR")

    # DETER com geometria (requer pip install agrobr[geo])
    gdf = await desmatamento.deter_geo(
        bioma="Amazônia", uf="PA",
        data_inicio="2024-01-01", data_fim="2024-06-30",
    )

    # Com metadados
    df, meta = await desmatamento.prodes(bioma="Cerrado", ano=2022, return_meta=True)

B3 Futuros Agro (v0.10.0)

from agrobr import b3
from datetime import date

async def main():
    # Ajustes diarios de futuros agricolas
    df = await b3.ajustes(data="13/02/2025")

    # Filtrar por contrato
    df = await b3.ajustes(data="13/02/2025", contrato="boi")

    # Serie historica de ajustes
    df = await b3.historico(contrato="boi", inicio=date(2025, 2, 10), fim=date(2025, 2, 14))

    # Posicoes em aberto (open interest)
    df = await b3.posicoes_abertas(data=date(2025, 12, 19))

    # Filtrar OI por contrato e tipo (futuro/opcao)
    df = await b3.posicoes_abertas(data=date(2025, 12, 19), contrato="boi", tipo="futuro")

    # Serie historica de OI
    df = await b3.oi_historico(contrato="boi", inicio=date(2025, 12, 15), fim=date(2025, 12, 19))

    # Listar contratos disponiveis
    print(b3.contratos())  # ['boi', 'cafe_arabica', 'cafe_conillon', 'etanol', 'milho', 'soja_cross', 'soja_fob']

    # Com metadados
    df, meta = await b3.ajustes(data="13/02/2025", return_meta=True)

CONAB Progresso de Safra (v0.10.0)

from agrobr import conab

async def main():
    # Progresso semanal de plantio/colheita
    df = await conab.progresso_safra()

    # Filtrar por cultura, estado e operação
    df = await conab.progresso_safra(cultura="Soja", estado="MT", operacao="Colheita")

    # Semana específica
    df = await conab.progresso_safra(semana_url="https://www.gov.br/conab/.../acompanhamento-...")

    # Listar semanas disponíveis
    semanas = await conab.semanas_disponiveis()

CONAB CEASA/PROHORT — Precos Atacado Hortifruti (v0.10.0)

from agrobr import conab

async def main():
    # Precos diarios de 48 produtos em 43 CEASAs
    df = await conab.ceasa_precos()

    # Filtrar por produto e/ou CEASA
    df = await conab.ceasa_precos(produto="tomate", ceasa="SAO PAULO")

    # Dimensoes
    produtos = conab.ceasa_produtos()      # 48 produtos
    ceasas = conab.lista_ceasas()          # 43 CEASAs com UF
    cats = conab.ceasa_categorias()        # FRUTAS/HORTALICAS

Modo Síncrono

from agrobr.sync import cepea, conab, ibge, datasets, nasa_power, bcb, comexstat
from agrobr.sync import abiove, usda, imea, deral, queimadas, desmatamento, b3
from agrobr.sync import mapbiomas
from agrobr.sync import alt

# Mesmo API, sem async/await
df = cepea.indicador('soja', inicio='2024-01-01')
safras = conab.safras('milho')
pam = ibge.pam('soja', ano=2023)
df = datasets.preco_diario('soja')
clima = nasa_power.clima_uf('MT', ano=2024)
credito = bcb.credito_rural(produto='soja', safra='2024/25')
exportacao = comexstat.exportacao('soja', ano=2024)

# v0.8.0
df = abiove.exportacao(ano=2024)
df = usda.psd('soja', market_year=2024)
df = imea.cotacoes('soja')
df = deral.condicao_lavouras('soja')
df = conab.serie_historica('soja', inicio=2020)

# v0.10.0
df = queimadas.focos(ano=2024, mes=9)
df = desmatamento.prodes(bioma="Cerrado", ano=2022)
gdf = desmatamento.prodes_geo(bioma="Cerrado", ano=2022, uf="MT")
gdf = desmatamento.deter_geo(bioma="Amazônia", uf="PA", data_inicio="2024-01-01")
df = b3.ajustes(data="13/02/2025")
df = b3.posicoes_abertas(data="2025-12-19", contrato="boi")
df = mapbiomas.cobertura(uf="MT", ano=2022)
df = mapbiomas.cobertura(nivel="municipio", estado="PA", municipio="Belém", ano=2020)

# IBGE PEVS, Leite, PIB
df = ibge.silvicultura('madeira_tora', ano=2023)
df = ibge.extracao_vegetal('acai', ano=2023)
df = ibge.leite_trimestral(trimestre='202303')
df = ibge.pib_agro(trimestre='202501')

# SICAR — Cadastro Ambiental Rural
df = alt.sicar.imoveis("DF")
df = alt.sicar.resumo("MT", municipio="Sorriso")

Suporte Polars

# Retorna polars.DataFrame em vez de pandas — suportado em todas as source APIs
df = await cepea.indicador('soja', as_polars=True)
df = await conab.safras('milho', as_polars=True)
df = await ibge.pam('soja', ano=2023, as_polars=True)
df = await b3.ajustes(data="13/02/2025", as_polars=True)
df = await bcb.credito_rural('soja', safra='2023/24', as_polars=True)
df = await inmet.estacao('A001', '2024-01-01', '2024-01-31', as_polars=True)

CLI

# CEPEA
agrobr cepea indicador soja --ultimo
agrobr cepea indicador milho --inicio 2024-01-01 --formato csv

# CONAB
agrobr conab safras soja --safra 2024/25
agrobr conab balanco milho

# IBGE
agrobr ibge pam soja --ano 2023 --nivel uf
agrobr ibge lspa milho --ano 2024 --mes 6

# Health check & diagnóstico
agrobr health
agrobr health --source cepea --deep
agrobr doctor --verbose
agrobr config show

Status das Fontes

Fonte	Status
CEPEA
Testes
Integração

O agrobr monitora automaticamente a disponibilidade das fontes. Use agrobr health --all para verificar localmente.

Datasets Disponíveis

Dataset	Descrição	Fontes
abate_trimestral	Abate de bovinos, suínos e frangos por UF	IBGE Abate
balanco	Oferta/demanda	CONAB
cadastro_rural	Cadastro Ambiental Rural (imóveis rurais por UF)	SICAR/GeoServer WFS
censo_agropecuario	Censo Agropecuário 1995/2006/2017 (10 temas)	IBGE Censo Agro
censo_agropecuario_historico	Série histórica Censo Agropecuário 1920-2006 (9 temas)	IBGE SIDRA
censo_agropecuario_legado	Censo 1995/96 — 6 temas legados (FTP)	IBGE FTP
censo_agropecuario_municipal_1985	Censo 1985 municipal — 53 temas via OCR (22 UFs)	IBGE PDFs
clima	Dados climáticos mensais/diários por UF ou estação	INMET → NASA POWER
comercio_internacional	Comércio internacional bilateral por HS code	UN Comtrade
condicao_lavouras	Condição semanal das lavouras do Paraná	DERAL
credito_rural	Crédito rural por cultura (programa, seguro, modalidade)	BCB/SICOR → BigQuery
custo_producao	Custos de produção	CONAB
desmatamento	Desmatamento PRODES/DETER — consolidado + alertas	INPE TerraBrasilis
estimativa_safra	Estimativas safra corrente	CONAB → IBGE LSPA
exportacao	Exportações agrícolas	ComexStat → ABIOVE
extrativismo_vegetal	Produção extrativista vegetal (açaí, castanha, erva-mate)	IBGE PEVS
fertilizante	Entregas de fertilizantes	ANDA
futuros_agricolas	Futuros agrícolas B3 (ajustes, histórico, posições)	B3
importacao	Importações agrícolas	ComexStat
leite_industrial	Aquisição e industrialização trimestral de leite por UF	IBGE Leite
movimentacao_portuaria	Movimentação portuária de carga (granel, geral, contêiner)	ANTAQ
oferta_demanda_global	Oferta/demanda global de commodities (USDA PSD)	USDA
pecuaria_municipal	Pecuária municipal (rebanhos e produção animal)	IBGE PPM
pib_agro	PIB agropecuário por setor e trimestre	IBGE SIDRA
preco_atacado	Preços de atacado hortifrúti em CEASAs	CONAB CEASA/PROHORT
preco_diario	Preços diários spot	CEPEA → cache
producao_anual	Produção anual consolidada	IBGE PAM → CONAB
progresso_safra	Progresso semanal semeadura/colheita	CONAB
queimadas	Focos de calor por satélite (6 biomas)	INPE
seguro_rural	Apólices e sinistros do seguro rural	MAPA PSR
serie_historica_safra	Série histórica de safras — 32 culturas desde 1976	CONAB
silvicultura	Produção silvicultural (eucalipto, pinus, carvão vegetal)	IBGE PEVS
uso_do_solo	Cobertura e uso da terra anual por UF/município	MapBiomas
zoneamento_agricola	Zoneamento agrícola de risco climático (ZARC)	MAPA/Embrapa

Fontes Suportadas

Fonte	Dados	Golden Test	Status
CEPEA	Indicadores de preços (20 produtos)	✅	Funcional
CONAB	Safras, balanço, custos, série histórica	✅	Funcional
IBGE	PAM, LSPA, PPM, Abate, PEVS, Leite, PIB, Censo Agro	✅	Funcional
NASA POWER	Climatologia diária/mensal (grid 0.5°)	✅	Funcional
BCB/SICOR	Crédito rural por cultura + séries temporais SGS + cotação PTAX + expectativas Focus	✅¹	Funcional
ComexStat	Exportações e importações por NCM/UF	✅¹	Funcional
ANDA	Entregas de fertilizantes	✅	Funcional
ABIOVE	Exportação complexo soja (volume/receita)	✅	Funcional
USDA PSD	Estimativas internacionais (produção/oferta/demanda)	✅¹	Funcional
IMEA	Cotações e indicadores Mato Grosso	✅	Funcional
DERAL	Condição das lavouras Paraná	✅	Funcional
INMET	Meteorologia (600+ estações)	✅¹	Requer token (AGROBR_INMET_TOKEN)
Notícias Agrícolas	Cotações (fallback CEPEA)	✅¹	Funcional
Queimadas/INPE	Focos de calor por satelite (6 biomas, 13 satelites)	✅	Funcional
Desmatamento PRODES/DETER	Desmatamento consolidado + alertas (TerraBrasilis WFS)	✅	Funcional
MapBiomas	Cobertura e uso da terra (1985-presente), nivel estado e municipio	✅	Funcional
CONAB Progresso	Progresso semanal de plantio/colheita por cultura e UF	✅	Funcional
B3 Futuros Agro	Ajustes diarios + posicoes em aberto (7 contratos agro)	✅	Funcional
CONAB CEASA/PROHORT	Precos atacado hortifruti (48 produtos, 43 CEASAs)	✅	Funcional
UN Comtrade	Comercio bilateral + trade mirror (~200 paises, HS codes)	✅¹	Funcional
ANTAQ	Movimentacao portuaria de carga (granel, geral, conteiner)	✅	Funcional
ANP Diesel	Precos revenda + volumes diesel por UF/municipio	✅	Funcional
MAPA PSR	Apolices e sinistros seguro rural (2006+, 27 UFs)	✅	Funcional
ANTT Pedagio	Fluxo de veiculos em pracas de pedagio (2010+, 200+ pracas)	✅	Funcional
SICAR	Cadastro Ambiental Rural — imoveis rurais por UF (7.4M+ registros, WFS)	✅	Funcional
ZARC	Zoneamento Agricola de Risco Climatico (janelas de plantio por municipio/cultura/solo)	✅	Funcional
Agrofit/MAPA (Defensivos)	Agrotoxicos registrados — formulados, autorizacoes, tecnicos (~8K produtos)	✅	Funcional
MapBiomas Alerta	Alertas de desmatamento via GraphQL (500K+ alertas, filtro data/fonte/bbox/uf)	✅	Requer token (AGROBR_MAPBIOMAS_ALERTA_TOKEN)
Lista Suja	Cadastro de empregadores (trabalho escravo) via XLSX	✅	Funcional
ANA/SNIRH	Hidrografia, pivos irrigacao, demanda irrigacao, disponibilidade hidrica (ArcGIS REST)	✅	Funcional
SFB	Florestas publicas (CNFP), concessoes florestais, IFN conglomerados (ArcGIS REST)	✅	Funcional
FUNAI	Terras indigenas (WFS geoserver.funai.gov.br) — ~740 TIs, filtros uf/fase/bbox	✅	Funcional
IBAMA	Embargos ambientais (WFS siscom.ibama.gov.br) — ~89K features, filtro uf/bbox	✅	Funcional
ICMBio	Unidades de conservacao federais (WFS geoservicos.inde.gov.br) — 344 UCs	✅	Funcional
INCRA	Territorios quilombolas (WFS cmr.funai.gov.br) — ~426 territorios	✅	Funcional
RNC/CultivarWeb	Cultivares registradas (~37K) e protegidas (~5K) — MAPA/SNPC	✅	Funcional
EMBRAPA Solos	Perfis de solo PronaSolos (34K+) + mapa pedologico SiBCS (2.8K poligonos)	✅	Funcional
Fundacao Rio Verde	Ensaios cultivares soja MT — ~97 cultivares x 4 epocas (PDF)	✅	Funcional

¹ Golden test com dados sintéticos — needs_real_data para validação com API real.

Contratos & Schemas

Cada dataset tem um contrato formal com validação automática. Schemas JSON gerados em agrobr/schemas/:

from agrobr.contracts import get_contract, list_contracts, validate_dataset

# Listar contratos registrados
list_contracts()
# ['abate_trimestral', 'ajuste_diario', 'balanco', 'censo_agropecuario',
#  'comercio_bilateral', 'conab_progresso', 'credito_rural', 'custo_producao',
#  'desmatamento_deter', 'desmatamento_prodes', 'estimativa_safra', 'exportacao',
#  'extrativismo_vegetal', 'fertilizante', 'focos_queimadas', 'leite_industrial',
#  'mapbiomas_cobertura', 'mapbiomas_transicao',
#  'anp_diesel_precos', 'anp_diesel_vendas', 'antt_pedagio_fluxo',
#  'antt_pedagio_pracas', 'mapa_psr_sinistros',
#  'censo_agropecuario_historico', 'censo_agropecuario_municipal_1985',
#  'mapa_psr_apolices', 'movimentacao_portuaria',
#  'pecuaria_municipal', 'posicoes_abertas', 'preco_atacado', 'preco_diario',
#  'producao_anual', 'sicar_imoveis', 'silvicultura', 'trade_mirror']

# Inspecionar contrato
contract = get_contract("preco_diario")
print(contract.primary_key)   # ['data', 'produto']
print(contract.to_json())     # Schema JSON completo

# Validação explícita (automática em todo fetch)
validate_dataset(df, "preco_diario")  # raises ContractViolationError

Garantias globais: nomes estáveis (só adicionam), tipos só alargam (int→float ok, float→int nunca), datas ISO-8601, breaking changes só em major version. Veja docs/contracts/ para detalhes por dataset.

Normalização Transversal

Funções para padronizar dados entre fontes:

from agrobr.normalize import (
    normalizar_cultura, municipio_para_ibge, coordenada_para_municipio,
    normalizar_uf, normalizar_safra,
)

normalizar_cultura("Soja em Grão")    # "soja"
normalizar_cultura("milho 2ª safra")  # "milho_2"
normalizar_cultura("coffee")          # "cafe"

municipio_para_ibge("Sorriso", "MT")  # 5107925
municipio_para_ibge("SAO PAULO", "SP")  # 3550308

coordenada_para_municipio(-12.74, -55.68)
# {'codigo_ibge': 5107925, 'nome': 'Sorriso', 'uf': 'MT'}

normalizar_uf("São Paulo")            # "SP"
normalizar_safra("24/25")             # "2024/25"

5571 municípios IBGE com centroides (geocodificação reversa offline), 35 culturas canônicas, 27 UFs. Dados via API IBGE Localidades e Malhas (livre para uso).

Diferenciais

• 38/38 fontes com golden tests — validação automatizada contra dados de referência
• Resiliência HTTP completa — retry centralizado em 38/38 clients, 429 handling, Retry-After
• 5800+ testes, 88% cobertura — benchmarks de escalabilidade (memory, volume, cache, async)
• Thread-safe cache — DuckDB store com locking para uso em MCP servers e multi-thread
• Camada semântica — datasets padronizados com fallback automático
• Contratos formais — schema versionado com validação automática, primary keys e constraints
• Schemas JSON — contratos exportados como JSON em agrobr/schemas/
• Normalização transversal — municípios IBGE, culturas, UFs, safras padronizados
• Modo determinístico — reprodutibilidade total para papers/auditorias
• Async-first para pipelines de alta performance
• Cache inteligente com DuckDB (analytics nativo + histórico permanente)
• Suporte pandas + polars
• Validação — Pydantic v2 + sanity checks estatísticos + fingerprinting de layout
• Alertas multi-canal (Slack, Discord, Email)
• CLI completo para debug e automação

Como Funciona

O agrobr mantém um cache local em DuckDB que acumula dados ao longo do tempo:

Dia 1:   Coleta 10 dias de dados → salva no DuckDB
Dia 30:  30 dias de histórico acumulado
Dia 365: 1 ano completo de dados locais

Consultas a períodos antigos são instantâneas (cache). Apenas dados recentes precisam de request HTTP.

Manter Dados Atualizados

Integre com Airflow, Prefect ou Dagster usando a API sync:

# Airflow task
@task
def extract_soja():
    from agrobr.sync import datasets
    df = datasets.preco_diario("soja")
    df.to_parquet("/data/soja.parquet")

Veja o guia completo de pipelines e o guia de ergonomia async.

Documentação

Documentação completa

• Guia Rápido
• Datasets — Contratos e garantias
• Fontes — 38 fontes documentadas
• API Reference
• Resiliência
• Portabilidade — Guia para portar o agrobr para R, Julia ou outras linguagens

Contribuindo

Contribuições são bem-vindas! Veja CONTRIBUTING.md para detalhes.

Licenças dos Dados

Importante: O agrobr é licenciado sob MIT, mas os dados acessados pertencem às suas respectivas fontes e possuem licenças próprias. Dados CEPEA/ESALQ, por exemplo, são CC BY-NC 4.0 (uso comercial requer autorização). Consulte docs/licenses.md para a tabela completa de fontes, licenças e classificações.

Licença

MIT - veja LICENSE para detalhes.