CEPEA - Centro de Estudos Avançados em Economia Aplicada¶

Licença: Dados CEPEA/ESALQ licenciados sob CC BY-NC 4.0. Uso comercial requer autorização do CEPEA (cepea@usp.br). Ref: Licença de uso de dados

Visão Geral¶

Campo	Valor
Instituição	ESALQ/USP
Website	cepea.org.br
Licença	CC BY-NC 4.0
Acesso agrobr	CEPEA direto, com fallback Notícias Agrícolas quando disponível

Origem dos Dados¶

Fonte Primaria¶

Página oficial: Indicadores do CEPEA
Acesso: Tentativa direta por HTTP; bloqueios e indisponibilidade podem acionar o fallback

Fonte Alternativa¶

Página: Cotações do Notícias Agrícolas
Tipo: Mirror autorizado dos indicadores CEPEA
Uso: Quando habilitado e disponível para o produto consultado

Produtos Disponíveis (22 identificadores, 20 indicadores)¶

O bezerro traz também valor_usd (coluna Valor US$) e peso_medio_kg (tabela Peso Médio da página); os demais produtos preenchem valor_usd quando o CEPEA publica o dólar.

Produto	Praca Principal	Unidade	Frequência
Soja	Paranagua/PR	BRL/sc60kg	Diaria
Soja Parana	Parana	BRL/sc60kg	Diaria
Milho	Campinas/SP	BRL/sc60kg	Diaria
Bezerro	Mato Grosso do Sul	BRL/cabeca	Diária
Boi Gordo	São Paulo/SP	BRL/@	Diaria
Cafe Arabica	São Paulo/SP	BRL/sc60kg	Diaria
Cafe Robusta	Espirito Santo	BRL/sc60kg	Diaria
Trigo	Parana + RS	BRL/ton	Diaria
Algodao	São Paulo/SP	cBRL/lb	Diaria
Arroz em casca	Rio Grande do Sul	BRL/sc50kg	Diaria
Acucar cristal	São Paulo/SP	BRL/sc50kg	Diaria
Açúcar refinado	São Paulo/SP	BRL/kg	Diária
Etanol hidratado	São Paulo/SP	BRL/L	Semanal
Etanol anidro	São Paulo/SP	BRL/L	Semanal
Frango congelado	São Paulo/SP	BRL/kg	Diaria
Frango resfriado	São Paulo/SP	BRL/kg	Diaria
Suíno vivo	MG, PR, RS, SC e SP (condição da praça preservada)	BRL/kg	Diária
Leite	UF e BRASIL, ao produtor	BRL/L	Mensal
Laranja industria	São Paulo/SP	BRL/cx40.8kg	Diaria
Laranja in natura	São Paulo/SP	BRL/cx40.8kg	Diaria

Metodologia CEPEA¶

O CEPEA calcula indicadores baseado em:

Pesquisa diaria com agentes de mercado
Media ponderada por volume negociado
Ajuste para qualidade padrão

Fonte: Metodologia CEPEA

Atualização e Defasagem¶

Aspecto	Valor
Horario de atualização	~17:00 - 18:00 (dias uteis)
Defasagem tipica	D+0 (mesmo dia)
Dias sem publicação	Fins de semana, feriados nacionais
Cache agrobr	Vale até a próxima virada das 18:00 BRT em dia útil, contada da última coleta do produto (Smart TTL)

Uso¶

Básico¶

import asyncio
from agrobr import cepea

async def main():
    # Janela recente disponível na fonte e no cache
    df = await cepea.indicador('soja')

    # Periodo especifico
    df = await cepea.indicador('milho', inicio='2024-01-01', fim='2024-12-31')

    # Ultimo valor disponivel
    ultimo = await cepea.ultimo('boi')
    print(f"Boi gordo: R$ {ultimo.valor}")

asyncio.run(main())

Com Metadados¶

df, meta = await cepea.indicador('soja', return_meta=True)

print(meta.source)
print(meta.source_url)
print(meta.fetched_at)
print(meta.from_cache)  # True/False

Schema dos Dados¶

Coluna	Tipo	Nullable	Descrição
`data`	date	Não	Data do indicador
`produto`	str	Não	Nome do produto
`praca`	str	Sim	Praca de referencia
`valor`	float	Não	Preço na unidade da linha; algodão em centavos de real por libra
`unidade`	str	Não	Unidade (BRL/sc60kg, etc)
`fonte`	str	Não	Fonte dos dados
`metodologia`	str	Sim	Descrição da metodologia
`anomalies`	str	Sim	Marcas da linha como texto JSON (ex.: `["valor_mantido"]`); nulo sem marca
`valor_usd`	float	Sim	Preço em dólar publicado na mesma linha; nulo quando o CEPEA não divulga, nas linhas do fallback Notícias Agrícolas e no cache anterior à migração 10
`peso_medio_kg`	float	Sim	Peso médio do bezerro (kg); nulo nos demais produtos

Cache¶

O CEPEA usa Smart TTL - o cache expira automaticamente as 18:00:

08:00 - Busca soja -> Cache valido ate 18:00
10:00 - Busca soja -> Usa cache
17:59 - Busca soja -> Usa cache
18:01 - Busca soja -> Cache expirou -> Busca fonte -> Válido até 18:00 do próximo dia útil

Coleta depois das 18:00, no sábado ou no domingo vale até as 18:00 do próximo dia útil (segunda a sexta; feriados não entram no cálculo). Um período fechado (fim anterior aos últimos 25 dias corridos) não consulta a página: sai do cache, ou da série histórica baixada quando ela ainda não cobre o período, com cache_expires_at nulo.

boi e boi_gordo, e cafe e cafe_arabica, são o mesmo indicador do CEPEA, e o cache guarda cada série uma vez, pelo nome que o datasets.preco_diario usa (boi e cafe). Pedir pelo outro nome lê as mesmas linhas, sem baixar de novo a página nem a série, e a coluna produto sai com o nome pedido. Linhas que versões anteriores gravaram sob o outro nome continuam valendo, sem migração do banco; com as 2 no mesmo dia e praça, vale a regra de precedência de sempre (a coleta mais recente da mesma fonte).

Funções Auxiliares¶

# Lista produtos disponiveis
produtos = await cepea.produtos()
# ['soja', 'soja_parana', 'milho', 'bezerro', 'cafe', 'cafe_arabica',
#  'cafe_robusta', 'boi', 'boi_gordo', 'trigo', 'algodao', 'arroz',
#  'acucar', 'acucar_refinado', 'frango_congelado', 'frango_resfriado', 'suino',
#  'etanol_hidratado', 'etanol_anidro', 'leite', 'laranja_industria',
#  'laranja_in_natura']

# Lista pracas para um produto
pracas = await cepea.pracas('soja')
# ['paranagua'] - corresponde a "Paranaguá/PR" na coluna praca

Cobertura e seleção das séries¶

A página do indicador publica uma janela recente, normalmente cerca de 15 pregões. O período anterior a ela vem da série histórica do CEPEA, a planilha que o CEPEA publica por indicador (desde 1996 a 2010, conforme o produto): na primeira consulta que precisa dela, o agrobr baixa a série inteira do produto e grava no DuckDB só os dias que o cache ainda não tem, e as consultas seguintes saem do cache. A série é baixada de novo quando o período pedido passa do último dia que ela publicou (o cache registra essa data no download), e nunca antes da virada das 18h do CEPEA seguinte ao download anterior. Laranja não tem série: antes da janela, o resultado traz só o que o cache acumulou, com aviso em validation_warnings e UserWarning. Com fim dentro dos últimos 25 dias corridos (as cerca de 15 datas publicadas), a página é consultada quando a última coleta do produto venceu ou, sem coleta registrada, quando falta no cache algum dia útil desse trecho do período pedido; dentro da validade, a resposta sai do cache, mesmo com um feriado ou com o dia de hoje ainda sem publicação. Com fim anterior a essa janela, a página não é consultada. force_refresh=True sempre consulta a fonte, e offline=True nunca consulta.

Na série, o dia com valor 0 (sem cotação) fica fora, como na página. O leite sai com 2 casas na série e com 4 na página: quando os 2 existem, vale a página, e source_details["pagina_desde"] traz o primeiro mês que veio dela. As linhas da série gravam parser_version 101, e o MetaInfo da consulta que baixou a série traz cada planilha em source_details["resources"] (URL, SHA-256, bytes e horário; a do peso do bezerro com papel serie_peso). Série indisponível avisa em validation_warnings e UserWarning; se o período ficar sem dado, indicador levanta SourceUnavailableError (ou ParseError, se a planilha mudou de layout).

Sem rede e sem nada no cache para o período, indicador e ultimo levantam SourceUnavailableError, com attempted_sources (as fontes tentadas e o cache); com cache, a resposta sai dele com StaleDataWarning. Com offline=True e o cache vazio, indicador devolve a tabela vazia, com from_cache=False e cache_expires_at nulo, e ultimo levanta SourceUnavailableError ("offline sem dado no cache").

Páginas com vários indicadores são selecionadas pelo título do produto, nunca pela posição da tabela. O suíno preserva as cinco praças da coluna Estado. A migração do cache remove as antigas linhas de suíno rotuladas incorretamente; dados corrigidos são coletados nas chamadas seguintes.

Para leite, data representa o primeiro dia do mês de referência, praca preserva a UF (ou BRASIL) e a unidade é BRL/L. A tabela de leite spot não integra essa série. ultimo("leite") usa uma janela mensal e pode retornar um mês anterior à publicação.

Leite não usa o fallback Notícias Agrícolas na API CEPEA. A página NA informa fechamento e referência separadamente, mas seu parser autônomo expõe o fechamento. A migração 9 preserva essas linhas legadas em quarentena, sem presumir uma defasagem fixa para convertê-las em mês de referência.

O açúcar refinado usa a página própria do indicador no site do CEPEA, em BRL/kg, e não a tabela do cristal. HTTP 200 sem tabela reconhecida também aciona o fallback Notícias Agrícolas, quando habilitado e disponível para o produto, com o aviso de licença habitual. A tabela sem a coluna de valor em reais reconhecida pelo cabeçalho ("Valor R$", "R$/litro", "Preço médio" no leite, "A Prazo" na laranja) também: o parser levanta ParseError e não usa outro número da linha, e uma coluna em US$ nunca vira preço em BRL.

Validação de preços¶

validate_sanity=True confere unidade e faixa para os 22 identificadores, incluindo os aliases cafe_arabica e boi_gordo. Unidade incompatível é marcada antes de comparar valores. Leite mensal e etanol semanal não recebem limites de variação diária. Consulte as faixas e seus limites de interpretação.

A coluna anomalies do DataFrame contém a lista serializada como texto JSON, ou None quando vazia, conforme o contrato de preco_diario.

Na soja em Paranaguá (soja), até 03/05/2015, o CEPEA mantinha o valor em reais do dia anterior quando não havia negócio efetivo elegível no dia (o valor "arbitrado", segundo as notas do CEPEA da época); a partir de 04/05/2015, com até 2 negócios no dia, as ofertas passaram a entrar no cálculo. Por isso a série repete o valor por semanas: 28 sequências de 5 pregões ou mais entre 28/12/2009 e 24/04/2015, a maior com 82 pregões em R$ 61,17 (29/09/2014 a 26/01/2015). O valor em dólar da mesma linha varia porque é o real convertido pelo câmbio do dia. O agrobr entrega o valor como publicado e marca com valor_mantido, em anomalies, cada pregão anterior a 04/05/2015 que repete o valor do pregão anterior da série; o 1º dia do trecho fica sem marca. Na série inteira são 551 linhas. A regra observa a igualdade publicada: uma repetição real anterior ao corte também recebe a marca, pois a série não identifica individualmente os dias sem negócio. A marca não depende de validate_sanity e vale na coleta, no cache, no offline e no datasets.preco_diario: para retorno diário ou volatilidade, descarte ou trate essas linhas. A soja do Paraná (soja_parana) e os demais produtos não recebem a marca.

Histórico legado no cache¶

A migração preserva automaticamente os originais afetados em indicadores_quarentena, no mesmo DuckDB, fora das consultas normais. Isso inclui suíno, séries CEPEA com seleção antiga e refinado legado do Notícias Agrícolas rotulado como saca em vez de kg. A atualização é transacional; falhas levantam CacheMigrationError. Registros já excluídos por versões anteriores não são recriados. Veja preservação e recuperação. A migração 10 acrescenta valor_usd e peso_medio_kg a indicadores antes das demais migrações, em passo idempotente fora da transação principal; registros anteriores ficam nulos nessas colunas até nova coleta. A migração 11 acrescenta anomalies a indicadores e à quarentena, no mesmo passo, e grava a marca de média semanal no cache. As linhas gravadas antes dela recebem ["media_semanal"] quando são do etanol hidratado ou anidro do Notícias Agrícolas, cujas duas páginas só publicam médias semanais, e lista vazia nas demais. Sem ela, a leitura do cache (offline ou dentro do prazo) devolvia a média semanal como cotação do dia.

Os parsers corrigidos identificam novas observações com versões CEPEA 2 e Notícias Agrícolas 3. MetaInfo.data_sources preserva a origem das linhas, inclusive quando selected_source="cache". O aviso de fallback não bloqueia por si só a leitura offline de outra fonte; aplicações com restrições por provedor devem avaliar esses metadados ou a coluna fonte.

Para a mesma data, produto e praça, CEPEA tem precedência sobre Notícias Agrícolas nas consultas normais e offline; ambas as observações continuam armazenadas. A migração 9 também corrige os rótulos legados de trigo (BRL/sc60kg → BRL/ton) e algodão (BRL/@ → cBRL/lb) do parser CEPEA anterior ao 2, sem modificar valores e preservando os originais em quarentena.