Contratos de Dados¶

O agrobr garante estabilidade de schema. Seu pipeline não vai quebrar.

Cada contrato é definido em Python (agrobr/contracts/) e exportado como JSON (agrobr/schemas/). Validação é automática: todo fetch() de dataset valida o DataFrame contra o contrato registrado.

Garantias Globais¶

Garantia	Descrição
Nomes estáveis	Colunas nunca mudam de nome (só adicionam)
Colunas estáveis presentes	Toda coluna `stable` existe no DataFrame; `nullable` permite valores nulos, não ausência da coluna
Tipos só alargam	int→float ok, float→int nunca
Datas tipadas	Colunas de data saem como `datetime64` (pandas), não como texto `YYYY-MM-DD`; com hora e fuso quando a fonte publica (ex.: `datetime64[ns, UTC]`)
Unidades explícitas	Coluna dedicada
Breaking = Major	Quebras só em versão major
Primary keys	Quando há chave definida, suas colunas existem e a combinação é única
Min/max constraints	Valores numéricos validados contra limites
Argumento desconhecido	Todo dataset recusa argumento fora da assinatura com `TypeError`, antes da rede
Tipos no polars	Com `as_polars=True`, cada coluna sai com o tipo do contrato (`int` → `Int64`, `float` → `Float64`, `str` → `String`, `bool` → `Boolean`), mesmo toda nula; a coluna de data toda nula sai `Datetime("ns")`

Datasets¶

A tabela lista os contratos documentados — não é idêntica a datasets.list_datasets(). bcb_focus, bcb_ptax e bcb_ptax_moedas são contratos de fonte reutilizados por expectativas_mercado, cotacoes_cambio e moedas_cambio; os nomes dos datasets não acrescentam aliases de contrato. A página PTAX reúne os contratos de cotações e catálogo.

Os quatro nomes de datasets Agrofit reutilizam os contratos agrofit_* existentes via _contract_name; não registram aliases de contrato. São 55 datasets e 90 contratos registrados. bcb_credito_rural_total é o contrato de fonte da função bcb.credito_rural_total, sem dataset, e bcb_credito_rural_registro, o do agregacao="registro" do bcb.credito_rural e do dataset credito_rural. autorizacoes_defensivos preserva linhas repetidas publicadas e não possui chave primária artificial.

series_economicas reutiliza bcb_sgs 3.0 sem alias de contrato. A seleção é por código ou alias SGS, com unidade e frequência dependentes da série. O dataset conserva a proveniência da consulta e não reconstitui revisões históricas.

Os dois datasets de cultivares reutilizam os novos contratos de fonte rnc_registradas e rnc_protegidas 1.0. As chaves são o número do registro RNC e o processo SNPC; certificados compartilhados por processos distintos são preservados. A consulta usa o cadastro corrente, com cache de aquisição de 24 horas e sem reconstrução histórica.

uso_do_solo valida a cobertura municipal das coleções 10 e 11 com mapbiomas_cobertura_municipal 1.1. As onze colunas incluem geocodigo e id_registro da publicação e o cod_municipio tirado do geocodigo; registros distintos com a mesma classificação territorial são preservados. A cobertura e as transições estaduais ficam nos seus contratos 2.0.

empregadores_lista_suja também reutiliza contrato de fonte existente, lista_suja_empregadores 2.0, sem alias. Sua chave de ID vale dentro do hash de uma publicação; documentos repetidos são preservados.

Dataset	Descrição	Fontes
unidades_conservacao	Unidades de conservação federais, estaduais e municipais, com RPPNs, do CNUC	CNUC/MMA
unidades_conservacao_federais	Cadastro corrente de unidades de conservação federais da camada ICMBio/INDE	ICMBio
precos_diesel	Preços semanais de diesel da ANP e médias mensais derivadas	ANP
moedas_cambio	Catálogo corrente de moedas do serviço PTAX/BCB	BCB
expectativas_mercado	Expectativas anuais e mensais de mercado do Focus/BCB	BCB
cotacoes_cambio	Cotações e paridades cambiais dos boletins PTAX/BCB	BCB
autorizacoes_defensivos	Autorizações de uso com multiplicidade publicada — `agrofit_autorizacoes` v1.1	Agrofit/MAPA
composicao_defensivos	Componentes e concentrações por família e registro — `agrofit_composicao` v1.0	Agrofit/MAPA
defensivos_formulados	Produtos formulados por registro — `agrofit_formulados` v1.1	Agrofit/MAPA
defensivos_tecnicos	Produtos técnicos por registro — `agrofit_tecnicos` v1.1	Agrofit/MAPA
preco_diario	Preços diários spot	CEPEA
producao_anual	Produção anual consolidada	IBGE PAM → CONAB
empregadores_lista_suja	Cadastro corrente de empregadores do MTE — `lista_suja_empregadores` v2.0	MTE / Lista Suja
estimativa_safra	Estimativas v3.1 por levantamento CONAB ou mês LSPA	CONAB → IBGE LSPA; seleção explícita
balanco	Oferta/demanda	CONAB
credito_rural	Crédito rural por cultura	BCB/SICOR → BigQuery
cultivares_registradas	Cadastro RNC com registro textual — `rnc_registradas` v1.0	CultivarWeb/MAPA
cultivares_protegidas	Cadastro SNPC por processo, preservando término textual — `rnc_protegidas` v1.0	CultivarWeb/MAPA
bcb_sgs	Séries temporais por código, referências e histórico por blocos	BCB SGS
bcb_focus	Expectativas anuais/mensais, detalhe, base e cobertura	BCB Focus
bcb_ptax / bcb_ptax_moedas	Cotações por moeda/boletim e catálogo OData corrente	BCB PTAX
bcb_credito_rural_total	Crédito rural por UF e finalidade, sem produto, com a industrialização	BCB/SICOR (`RegiaoUF`)
bcb_credito_rural_registro	Crédito rural registro a registro (`agregacao="registro"`), com mês, fonte de recursos, modalidade e atividade	BCB/SICOR (`*RegiaoUFProduto`)
exportacao	Exportações agrícolas	ComexStat → ABIOVE
fertilizante	Entregas de fertilizantes	ANDA
importacao	Importações agrícolas	ComexStat
custo_producao	Custos de produção	CONAB
custo_sociobiodiversidade	Custos da sociobiodiversidade nas unidades publicadas	CONAB
pecuaria_municipal	Rebanhos e produção animal	IBGE PPM
abate_trimestral	Abate de bovinos, suínos e frangos	IBGE Abate
censo_agropecuario	Censo Agropecuário 1995/2006/2017 (11 temas)	IBGE Censo Agro
censo_agropecuario_legado	Censo Agropecuário 1995/96 — 6 temas legados (FTP)	IBGE FTP
censo_agropecuario_historico	Série histórica Censo Agropecuário 1920-2006 (9 temas, até UF)	IBGE SIDRA
censo_agropecuario_municipal_1985	Censo 1985 — 53 tabelas municipais, casa a casa, com o status de cada casa	IBGE PDFs
cadastro_rural	Cadastro Ambiental Rural	SICAR
clima	Clima mensal por UF; diário/horário por estação	INMET API → INMET ZIP → NASA POWER (UF)
comercio_internacional	Comércio internacional bilateral (HS codes)	UN Comtrade
condicao_lavouras	Condição das lavouras paranaenses	SEAB/DERAL
desmatamento	Desmatamento PRODES e alertas DETER por bioma	INPE
embarques_anec	Embarques semanais por porto e produto	ANEC
embarques_mensais_anec	Volumes mensais, estimativas e faixas por edição	ANEC
comparacao_anual_anec	Comparação mensal entre anos por edição	ANEC
destinos_anec	Participação dos destinos no período acumulado	ANEC
silvicultura	Produção silvicultural (IBGE PEVS)	IBGE PEVS
extrativismo_vegetal	Produção extrativista vegetal (IBGE PEVS)	IBGE PEVS
leite_industrial	Leite trimestral (aquisicao/industrializacao)	IBGE Leite
lspa	Estimativas mensais de produção agrícola	IBGE LSPA
oferta_demanda_global	Oferta/demanda global (USDA PSD)	USDA
pib_agro	PIB agropecuário por setor e trimestre	IBGE SIDRA
preco_atacado	Preços de atacado em CEASAs — `preco_atacado` v2.0	CONAB CEASA/PROHORT
progresso_safra	Progresso semanal semeadura/colheita	CONAB
queimadas	Focos de calor por satélite	INPE
futuros_agricolas	Futuros agrícolas B3 (ajustes, histórico, posições)	B3
posicionamento_fundos	Posicionamento de fundos por categoria de trader (COT)	CFTC
movimentacao_portuaria	Movimentação portuária de cargas ⚠️ (fonte fora do ar)	ANTAQ
seguro_rural	Seguro rural — apólices (`mapa_psr_apolices` v2.1) e sinistros (`mapa_psr_sinistros` v1.2)	MAPA PSR
serie_historica_safra	Série histórica de safras (45 produtos)	CONAB
producao_acucar_etanol	Açúcar, etanol de cana e de milho e ATR por safra e UF (série industrial da cana)	CONAB
series_economicas	Séries por código ou alias SGS, intervalo e últimas observações	BCB SGS
uso_do_solo	Cobertura e uso da terra (MapBiomas)	MapBiomas
zoneamento_agricola	Zoneamento agrícola de risco climático (ZARC)	MAPA/Embrapa

Schemas JSON¶

Cada contrato gera automaticamente um arquivo JSON em agrobr/schemas/:

from agrobr.contracts import get_contract, list_contracts, generate_json_schemas

# Listar contratos registrados
list_contracts()

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

# Validação (automática em todo fetch, ou manual)
from agrobr.contracts import validate_dataset
validate_dataset(df, "preco_diario")  # raises ContractViolationError

# Gerar todos os JSONs
generate_json_schemas("agrobr/schemas/")

Uso¶

from agrobr import datasets

# Listar datasets
print(datasets.list_datasets())
# 55 datasets

# Listar produtos de um dataset
datasets.list_products("preco_diario")
# ['soja', 'milho', 'boi', 'bezerro', 'cafe', 'cafe_robusta', 'trigo', 'algodao']

# Info de um dataset
datasets.info("preco_diario")
# {'name': 'preco_diario', 'sources': ['cepea'], ...}

# Ficha em texto de um dataset e de todos
print(datasets.describe("preco_diario"))
print(datasets.describe_all())

# O objeto do dataset (uma cópia): info e fetch com os argumentos de datasets.preco_diario
ds = datasets.get_dataset("preco_diario")
df = await ds.fetch("soja", inicio="2024-01-01")

Nome desconhecido em get_dataset, info, list_products ou describe levanta UnknownNameError, que herda de InvalidParameterError e de KeyError, com os nomes válidos na mensagem.

O contract_version do info() é o do modo padrão. Nos datasets com mais de um modo (desmatamento, futuros_agricolas, seguro_rural, uso_do_solo, clima e credito_rural), cada modo valida o seu contrato: o describe lista todos, um por linha, abaixo de Contract:, e o MetaInfo.contract_version de cada consulta traz o do modo usado.

Fallback Automático¶

O fallback automático aplica-se aos datasets com fontes alternativas configuradas, respeitando a seleção e a cobertura da consulta. Datasets com fonte única, como os quatro Agrofit, não possuem fallback para outra instituição:

preco_diario: CEPEA → Notícias Agrícolas → cache DuckDB (dentro do cepea.indicador)
producao_anual: IBGE PAM → CONAB
estimativa_safra: CONAB → IBGE LSPA
balanco: CONAB
credito_rural: BCB/SICOR → BigQuery (basedosdados)
exportacao: ComexStat → ABIOVE
fertilizante: ANDA
custo_producao: CONAB
custo_sociobiodiversidade: CONAB
producao_acucar_etanol: CONAB
clima: INMET API → INMET ZIP → NASA POWER (somente UF)
futuros_agricolas: B3

MetaInfo¶

Toda chamada com return_meta=True retorna metadados de proveniência:

df, meta = await datasets.preco_diario("soja", return_meta=True)

print(meta.source)            # Fonte usada
print(meta.dataset)           # Nome do dataset
print(meta.contract_version)  # Versão do contrato
print(meta.records_count)     # Registros retornados
print(meta.from_cache)        # Se veio do cache
print(meta.attempted_sources) # Fontes tentadas, incluindo cascatas internas
print(meta.selected_source)   # Fonte real que forneceu os dados
print(meta.snapshot)          # Data de corte (modo determinístico)
print(meta.license)           # Classificação de licença do dado (docs/licenses.md)

Se um adaptador aciona uma cascata interna, attempted_sources, selected_source e from_cache preservam essa proveniência. Uma fonte simples mantém o nome do adaptador do dataset.

license é a classificação de licença do dado (livre, nc, zona_cinza ou restrito, da tabela de licenças): a mais restritiva entre as fontes de data_sources (o CEPEA com o fallback da Notícias Agrícolas sai nc) ou, sem elas, a da fonte selecionada. Vem da tabela agrobr.constants.LICENCAS, a mesma da documentação; fonte fora da tabela dá None.

Proveniência física.

source_url é o recurso que deu o dado, como a consulta com os filtros ou o arquivo baixado. Token e credencial saem como [REDACTED]. A página institucional, quando ajuda, fica em source_details.
Com um corpo só, raw_content_hash é o SHA-256 completo dele e raw_content_size é o tamanho em bytes.
fetch_timestamp é o horário UTC da aquisição do corpo que o topo descreve, e o dataset repassa o da fonte:
corpo recebido agora: a hora dessa aquisição;
corpo lido do cache (por exemplo, o ZIP do INMET, o Acervo Fundiário, a ANEC, o RNC, o ZARC e o Agrofit): a hora da aquisição original, igual ao fetched_at;
vários corpos: a aquisição mais recente entre eles, igual ao fetched_at;
registros do cache DuckDB do CEPEA: a hora da coleta original, igual ao fetched_at (ver abaixo).
Com vários corpos (páginas, anos, períodos ou consultas), raw_content_hash fica nulo e raw_content_size fica zero. O INMET (resources), o PSR (corpos), o IBGE (consultas, na SIDRA) e as séries da CONAB (publicacao.series) listam cada corpo em source_details, com URL e SHA-256.
Um corpo auxiliar que entra no dado fica em source_details, com URL, SHA-256 e bytes, e o topo descreve o corpo dos registros. No IMEA, o catálogo que dá o nome dos indicadores sai em indicadores_url, indicadores_sha256 e indicadores_bytes.
O dado que o CEPEA lê do cache DuckDB (source igual a cache ou cache_fallback) sai com raw_content_hash nulo e raw_content_size zero, porque o cache guarda registros, não o corpo. O fetched_at e o fetch_timestamp são a hora da coleta original, a mais recente entre os registros devolvidos.
Quando source_details traz hash_kind ou raw_content_hash_kind igual a resource_manifest_sha256 (BCB, Comtrade, Embrapa Solos, FUNAI, PRODES/DETER, INCRA e SICAR), raw_content_hash é o SHA-256 do manifesto das consultas, não de um corpo HTTP, e raw_content_size é o tamanho desse manifesto. O manifesto leva a hora de cada recurso (fetched_at) nessas fontes, menos no SICAR, e também na ANP com mais de um arquivo (raw_hash_kind): o hash identifica a aquisição e muda a cada chamada, mesmo com o conteúdo igual. Para saber se o conteúdo mudou, compare o sha256 de cada item de source_details["resources"].
Na ANTT (fluxo_pedagio) e nos custos da CONAB (custo_producao), o hash_kind é próprio (sha256_canonical_utf8_query_and_acquisition_manifest e sha256_canonical_utf8_query_acquisition_selection_manifest), com a mesma regra: hash e tamanho são os do manifesto. O total recebido, com tentativas e falhas, fica em source_details["received_bytes"], e o dos arquivos que entraram no dado (CSVs na ANTT e planilha na CONAB), em source_details["data_file_bytes"].
Na NASA POWER, o hash é o da lista de recibos em source_details["http_receipts"], e o tamanho soma os corpos HTTP.

Coleta bruta¶

O modo bruto não é um dataset nem um contrato tabular: o manifesto.jsonl tem contrato próprio, versionado à parte (schema 1.0.0). Veja Coleta bruta.