title: anp-fetcher — Dados abertos e estatísticos da ANP description: Catálogo da ANP: preços de combustíveis, vendas, produção, comércio exterior, royalties, movimentação, qualidade e produção por poço.

Petróleo, Gás e Biocombustíveis (ANP)¶

Dados abertos e estatísticos da ANP (Agência Nacional do Petróleo, Gás Natural e Biocombustíveis).

anp-fetcher descobre datasets a partir de um catálogo declarativo (sem chamadas de rede) e baixa cada um com manifesto de proveniência (quantilica-core), organizados por grupo. Ele foi projetado para esconder toda a complexidade e instabilidade da fonte original.

Pegadinhas da fonte oficial (que o anp-fetcher resolve para você)

Convenção de nome de arquivo muda ao longo do tempo: Ex.: preços mensais de diesel/GNV usam precos-{produto}-{mm}.csv até 2025 e {mm}-dados-abertos-precos-{produto}.{ext} a partir de 2026. Além disso, a partir de 2026, certos dados saem em .xlsx em vez de .csv. O fetcher tenta a extensão principal e possui URLs de fallback dinâmicas.
Separador de campo mutável: Royalties por união/estado/município têm três eras de nomenclatura (royalties_uniao_2018.csv → royalties-uniao-2019.csv).
Sem API: Os dados são arquivos estáticos servidos a partir de páginas do gov.br/anp; não há endpoint consultável. O catálogo da Quantilica resolve isso com hardcoding inteligente e lógica de predição temporal.

Instalação¶

# Via CLI unificada (recomendado)
quantilica install anp

# Ou como biblioteca no seu projeto
uv add anp-fetcher --index https://index.quantilica.com/simple/

Requisitos: Python 3.12+

CLI¶

quantilica anp <command> [args]

Comandos:
  sync [GRUPOS...] [-o DIR] [--dry-run] [--verbose]
        Sincronizar datasets. Sem GRUPOS, baixa todos.
  list
        Listar todos os datasets do catálogo, sem baixar.

DIR padrão é /data/anp.

Exemplos¶

# Baixar todos os grupos
quantilica anp sync

# Dados estatísticos específicos
quantilica anp sync ie pp -o ./dados/anp

# Todos os grupos de preços de combustíveis (SHPC) de uma vez
quantilica anp sync shpc-ca shpc-glp shpc-diesel-gnv shpc-gasolina-etanol shpc-glp-mensal shpc-4s

# Listar sem baixar
quantilica anp sync --dry-run

Fases dos Dados: Abertos vs Estatísticos¶

O catálogo unifica duas fontes principais da ANP:

Dados Estatísticos (Fase 1): Consolidados em planilhas (XLS/XLSX). Trazem totalizadores agregados (ex: ie para Importações/Exportações, pp para Processamento). Útil para visões macro e anuários.
Dados Abertos: Microdados granulares (geralmente em .csv ou .zip). Trazem os registros linha a linha (ex: vendas por município, preços por posto). Essencial para modelos de machine learning e painéis interativos.

Preços de Combustíveis (`shpc-*`)¶

O Sistema de Levantamento de Preços (SHPC) é vasto e se divide em seis grupos. Não existe um macro-alias shpc: informe os grupos que precisar. O alias precos-combustiveis cobre apenas o shpc-ca.

Os seis grupos da base de preços, desde 2004: - shpc-ca: Combustíveis automotivos (Semestral, 2004–2025) - shpc-glp: GLP P13 (Semestral, 2004–2025) - shpc-diesel-gnv: Diesel e GNV (Mensal, 2023–hoje) - shpc-gasolina-etanol: Gasolina e Etanol (Mensal, 2023–hoje) - shpc-glp-mensal: GLP (Mensal, 2023–hoje) - shpc-4s: Últimas 4 semanas (Snapshot dinâmico)

Cookbook: Lendo o histórico do SHPC em Polars¶

Uma vez que você baixou os grupos shpc-*, você terá dezenas de zips e csvs históricos. Para carregar tudo eficientemente:

import polars as pl
from pathlib import Path

# Como a ANP altera encodings e separadores, uma leitura unificada
# robusta em LazyFrames usa inferência agressiva e preenchimento de nulos.
# (arquivos antigos do `shpc-ca` vêm em .zip e ficam fora deste glob)
df_lazy = pl.scan_csv(
    "data/anp/shpc-*/*.csv",
    separator=";",
    infer_schema_length=0, # Ler tudo como string primeiro para evitar erros de casting
    ignore_errors=True
)

# Filtre apenas o que precisa antes de coletar para a RAM
gasolina_sp = (
    df_lazy
    .filter(pl.col("Estado - Sigla") == "SP")
    .filter(pl.col("Produto") == "GASOLINA")
    .collect()
)

Datasets¶

Dados Estatísticos (XLS/XLSX)¶

Grupo	Descrição
`ie`	Importações e Exportações
`pp`	Processamento de Petróleo
`pb`	Produção de Biocombustíveis
`ppg`	Produção de Petróleo e Gás Natural
`vdpb`	Vendas de Derivados de Petróleo e Biocombustíveis

Dados Abertos — Vendas, Produção e Comércio Exterior¶

Grupo	Descrição
`vdpb-abertos`	Vendas de derivados e biocombustíveis (por produto, segmento e município)
`pp-abertos`	Processamento de petróleo e produção de derivados
`producao-el`	Produção de petróleo/LGN/gás natural por estado e localização
`pb-abertos`	Produção de biocombustíveis (biodiesel, etanol)
`ie-abertos`	Importações e exportações (petróleo, gás natural, derivados, etanol)
`producao-poco-abertos`	Produção de petróleo e gás natural por poço
`producao-fdp-mar` / `producao-fdp-terra`	Produção por campo — mar / terra

Dados Abertos — Logística, Infraestrutura e Regulação¶

Grupo	Descrição
`comercializacao-gn`	Comercialização de gás natural
`movimentacao-terminais`	Movimentação de terminais aquaviários
`armazenagem-terminais`	Capacidade de armazenagem de terminais
`tancagem`	Tancagem do abastecimento nacional de combustíveis
`pmqc`	Monitoramento da qualidade dos combustíveis
`incidentes`	Incidentes de segurança operacional em E&P
`rodadas`	Rodadas de licitações
`concessionarios`	Relação de concessionários e país de origem
`revendedores` / `revendas-glp`	Cadastro de revendedores varejistas
`royalties`	Participações governamentais (royalties, participação especial)

Execute quantilica anp list para a lista completa.

Saiba Mais¶

Arquitetura do Ecossistema — Design do sistema