Skip to content

README.md

Latest commit

 

History

History
129 lines (92 loc) · 3.66 KB

README.md

File metadata and controls

129 lines (92 loc) · 3.66 KB

comex-fetcher: Coletor de dados de comércio exterior brasileiro

License: MIT Python

Funções para download de dados de comércio exterior publicados pelo Ministério do Desenvolvimento, Indústria, Comércio e Serviços (MDIC). Suporta exportações, importações, dados municipais, série histórica NBM e tabelas auxiliares de códigos (NCM, países, UF, via, etc.).

Este pacote foi anteriormente distribuído como comexdown. Veja o guia de migração abaixo.

Instalação

pip install git+https://github.com/Quantilica/comex-fetcher.git

Uso Rápido

import comex_fetcher
from pathlib import Path

data_dir = Path("./dados")

# Exportações + importações de 2023
comex_fetcher.get_year(data_dir, year=2023)

# Apenas exportações
comex_fetcher.get_year(data_dir, year=2023, exp=True)

# Tabela de códigos NCM
comex_fetcher.get_table(data_dir, table="ncm")

CLI

comex-fetcher <comando> [argumentos]

Comandos:
  trade ANOS [-exp] [-imp] [-mun] [-o CAMINHO]
        Baixar transações comerciais para um ano, intervalo (2018:2023) ou
        'complete'. -exp/-imp restringem a direção; padrão baixa ambas.
        -mun adiciona dados no nível municipal (1997+).
  table [TABELAS...] [-o CAMINHO]
        Baixar tabelas de códigos auxiliares.
        Execute sem argumentos para listar as disponíveis.
  all [-y] [-o CAMINHO]
        Baixar tudo. Pede confirmação exceto com -y.

# Exportações + importações de 2023
comex-fetcher trade 2023 -o ./dados

# Apenas importações, 2018–2023, com dados municipais
comex-fetcher trade 2018:2023 -imp -mun -o ./dados

# Todas as tabelas auxiliares
comex-fetcher table all -o ./dados

API Python

from pathlib import Path
import comex_fetcher

data_dir = Path("./dados")

# Transações por ano — NCM (1997+)
comex_fetcher.get_year(data_dir, year=2023)
comex_fetcher.get_year(data_dir, year=2023, imp=True, mun=True)

# Série histórica NBM (1989–1996)
comex_fetcher.get_year_nbm(data_dir, year=1995)

# Arquivos completos (todos os anos consolidados)
comex_fetcher.get_complete(data_dir)

# Tabela de código auxiliar
comex_fetcher.get_table(data_dir, table="pais")

# Tudo de uma vez
comex_fetcher.download_all(data_dir)

Datasets Disponíveis

Grupo Datasets
Transações (NCM, 1997+) exp, imp, exp-mun, imp-mun
Histórico (NBM, 1989–96) exp-nbm, imp-nbm
Completos (arquivo único) exp-completa, imp-completa, exp-mun-completa, imp-mun-completa
Validação exp-validacao, imp-validacao, exp-mun-validacao, imp-mun-validacao
REPETRO exp-repetro, imp-repetro
Tabelas auxiliares ncm, sh, cuci, cgce, isic, siit, fat-agreg, unidade, ppi, ppe, grupo, pais, pais-bloco, uf, uf-mun, via, urf, isic-cuci, nbm, ncm-nbm

Migração de comexdown

Se você usava o pacote comexdown, atualize a instalação e os imports:

pip uninstall comexdown
pip install git+https://github.com/Quantilica/comex-fetcher.git
# Antes
import comexdown
comexdown.get_year(data_dir, year=2023)

# Depois
import comex_fetcher
comex_fetcher.get_year(data_dir, year=2023)

Desenvolvimento

git clone https://github.com/Quantilica/comex-fetcher.git
cd comex-fetcher
uv sync --dev
uv run pytest

Licença

MIT — veja LICENSE.