API ANEC¶

O módulo ANEC fornece embarques semanais de grãos e oleaginosas por porto, agregados mensais, comparação anual, destinos e acesso aos relatórios PDF.

Os dados são classificados como zona_cinza; a primeira chamada às funções tabulares emite UserWarning. Veja a página da fonte.

Embarques semanais¶

`embarques`¶

async def embarques(
    *,
    ano: int,
    semana: int | None = None,
    porto: str | None = None,
    produto: str | None = None,
    tipo: Literal["efetivado", "programado"] | None = None,
    use_cache: bool = True,
    as_polars: bool = False,
    return_meta: bool = False,
    **kwargs: Any,
) -> pd.DataFrame | tuple[pd.DataFrame, MetaInfo]

Parâmetro	Tipo	Descrição
`ano`	`int`	Ano da edição, de 2026 ao ano corrente; publicação depende do catálogo
`semana`	`int \\| None`	Semana do relatório; `None` seleciona o artigo mais recente do ano
`porto`	`str \\| None`	Filtro de porto, sem distinção de caixa ou acento
`produto`	`str \\| None`	Alias de produto aceito pela fonte ANEC
`tipo`	`str \\| None`	`efetivado` (`last_week`) ou `programado` (`current_week`)
`use_cache`	`bool`	Usa o cache de PDF quando `True`
`as_polars`	`bool`	Retorna `polars.DataFrame` quando `True`
`return_meta`	`bool`	Retorna `(DataFrame, MetaInfo)` quando `True`

ano, semana fora de 1–53, produto e tipo inválidos levantam InvalidParameterError antes de consultar o catálogo ou baixar o PDF.

Colunas: porto, produto, periodo, valor_ton, ano, semana, data_inicio e data_fim (veja a fonte). valor_ton usa dtype Float64 e recebe pd.NA quando o PDF não informa o volume.

Tabelas agregadas do relatório¶

`embarques_mensais`¶

async def embarques_mensais(
    *,
    ano: int,
    semana: int | None = None,
    produto: str | None = None,
    use_cache: bool = True,
    as_polars: bool = False,
    return_meta: bool = False,
    **kwargs: Any,
) -> pd.DataFrame | tuple[pd.DataFrame, MetaInfo]

Colunas: ano, mes, produto, valor_ton, eh_estimativa, valor_min_ton, valor_max_ton.

`comparacao_anual`¶

async def comparacao_anual(
    *,
    ano: int,
    semana: int | None = None,
    produto: str | None = None,
    use_cache: bool = True,
    as_polars: bool = False,
    return_meta: bool = False,
    **kwargs: Any,
) -> pd.DataFrame | tuple[pd.DataFrame, MetaInfo]

Colunas: mes, produto, valor_2025, valor_2026, valor_base_ton, valor_comparacao_ton, ano_base, ano_comparacao, eh_estimativa.

Schema de fonte 1.2. Prefira valor_base_ton e valor_comparacao_ton com seus anos explícitos. As colunas legadas valor_2025/valor_2026 contêm somente valores daqueles anos literais; ano ausente fica nulo. Anos em rodapés editoriais não substituem cabeçalhos da tabela. Cabeçalhos ausentes ou incompatíveis continuam gerando ParseError.

`destinos`¶

async def destinos(
    *,
    ano: int,
    semana: int | None = None,
    produto: str | None = None,
    use_cache: bool = True,
    as_polars: bool = False,
    return_meta: bool = False,
    **kwargs: Any,
) -> pd.DataFrame | tuple[pd.DataFrame, MetaInfo]

Colunas: produto, destino, share_pct, ano, mes_inicio, mes_fim.

As três funções usam ano, semana, use_cache, as_polars e return_meta como embarques(). produto aceita os mesmos aliases, com duas diferenças: comparacao_anual() aceita também "total_products", o agregado publicado; destinos() aceita só soja, farelo de soja, milho e trigo, e outro produto levanta InvalidParameterError antes do download.

Artigos e PDFs¶

`articles_disponiveis`¶

async def articles_disponiveis(year: int) -> list[dict[str, Any]]

Retorna dicionários com id, title, slug, pdf_url, created_at, media_updated_at, week e year.

`list_articles`¶

async def list_articles(year: int) -> list[ANECArticle]

Retorna os boletins semanais do ano como modelos ANECArticle. Artigo cujo título não segue ANEC - NN.AAAA é ignorado com UserWarning que cita o título.

`fetch_latest_pdf`¶

async def fetch_latest_pdf(
    year: int | None = None,
    *,
    use_cache: bool = True,
) -> tuple[bytes, str, ANECArticle]

Retorna os bytes, a URL e o modelo do artigo mais recente. year=None usa o ano-calendário corrente.

`fetch_pdf_bytes`¶

async def fetch_pdf_bytes(
    article: ANECArticle,
    *,
    use_cache: bool = True,
) -> tuple[bytes, str]

Retorna os bytes do PDF e sua URL.

`ANECArticle`¶

ANECArticle(
    *,
    id: int,
    cuid: str,
    title_en: str,
    slug_en: str,
    created_at: datetime,
    pdf_url: str,
    media_updated_at: datetime,
)

A propriedade week_year extrai a tupla (semana, ano) do título.

Exemplos¶

from agrobr import anec

df = await anec.embarques(ano=2026, produto="soja", tipo="efetivado")
mensal = await anec.embarques_mensais(ano=2026, produto="milho")
comparacao = await anec.comparacao_anual(ano=2026)
destinos = await anec.destinos(ano=2026, produto="farelo de soja")
artigos = await anec.articles_disponiveis(2026)

Versão síncrona¶

from agrobr.sync import anec

df = anec.embarques(ano=2026, produto="soja")

Proveniência da edição e catálogo¶

As três tabelas agregadas também incluem ano_relatorio, semana_relatorio, edicao_id, publicado_em e revisado_em. Schemas de fonte mensal/destinos permanecem 1.1; comparação anual é 1.2. Os contratos dos datasets continuam em 1.0.

Categorias anuais ausentes do mapa configurado são descobertas no catálogo oficial. Ano explícito sem publicação gera SourceUnavailableError, sem retornar edição anterior. fetch_latest_pdf(year=None) pode procurar anos anteriores suportados. Resultados vazios do catálogo são cacheados por ano durante AGROBR_ANEC_LIST_TTL segundos (padrão 300); zero desativa esse cache. Falhas de parsing ou rede não são cacheadas como ano sem publicação.

Integridade da leitura do PDF¶

Cabeçalhos semanais e mensais incompletos geram ParseError, em vez de devolver apenas as colunas reconhecidas. Vale o cabeçalho com os seis produtos ou com os quatro das edições até a W2/2026; coluna sem nome de produto gera ParseError. A soma dos portos de cada coluna semanal é conferida com a linha TOTAL publicada, e a divergência sai em aviso, sem mudar os valores. Em destinos, a leitura termina no total da tabela e exclui os números desenhados no mapa. Quadros rasterizados ainda podem retornar vazio com aviso. Os valores e percentuais de cada quadro são preservados, inclusive quando os totais publicados em outros quadros divergem.

API ANEC¶

Embarques semanais¶

embarques¶

Tabelas agregadas do relatório¶

embarques_mensais¶

comparacao_anual¶

destinos¶