FipeCrawler

Crawler em Python para exportar a Tabela FIPE em CSV usando a API v2 (Parallelum/Deivid Fortuna).

API v2 Docs: https://deividfortuna.github.io/fipe/v2/

Suporta tipos de veículo: carros, motos, caminhoes.

Estrutura do Projeto

.
├── fipe_crawler.py          # CLI mínimo (apenas orquestra): parse de args, .env e delega para o pacote
├── fipecrawler/             # Módulos com a lógica de negócio
│   ├── __init__.py          # Reexporta constantes e classes principais
│   ├── http.py              # Sessões HTTP, retries/backoff, rate limit utilitário
│   ├── api.py               # Funções de acesso à API FIPE (brands/models/years/price)
│   ├── state.py             # Checkpoint (full scan) e helpers de CSV
│   ├── logging.py           # Helpers para logs padronizados
│   ├── export.py            # Classe Exporter (exporta um tipo para CSV)
│   └── fullscan.py          # Classe FullScanner (varredura completa com limite diário)
├── requirements.txt
├── .env                     # Configurações (TOKEN, REFERENCE, limites, etc.)
└── .gitignore

Observação: fipe_crawler.py não contém mais lógica de coleta; ele apenas chama fipecrawler.Exporter e fipecrawler.FullScanner.

Requisitos

• Python 3.9+
• Pip (gerenciador de pacotes)

Instale as dependências:

pip install -r requirements.txt

Configuração (.env)

Crie/edite o arquivo .env na raiz do projeto com:

TOKEN=SEU_TOKEN_AQUI
# opcional
REFERENCE=308

Observações:

• O TOKEN é usado como X-Subscription-Token nas requisições v2.
• Você pode informar --token/--reference via CLI; se presentes, eles têm precedência sobre o .env.

Parâmetros para Full Scan

Adicione também (valores exemplo):

# Limite diário de requisições do seu plano
DAILY_LIMIT=500
# Margem de segurança: quando faltarem N requisições para o limite, pausa e retoma no dia seguinte
LIMIT_MARGIN=10
# Pasta de saída do full scan
FULL_SCAN_DIR=full_scan

Uso

Execute o script fipe_crawler.py escolhendo o tipo e o arquivo de saída:

python fipe_crawler.py --type carros --out fipe_carros.csv

Listar referências disponíveis (code,month):

python fipe_crawler.py --list-references

Full scan (varre carros -> motos -> caminhoes, respeitando limite diário):

python fipe_crawler.py --full-scan

O CLI resolve automaticamente a referência mais recente quando --reference não é informado ou é latest.

Detalhes do full scan:

• Usa DAILY_LIMIT e LIMIT_MARGIN do .env.
• Pausa automaticamente quando restarem LIMIT_MARGIN requisições; salva checkpoint em .state/full_scan.json.
• Retoma de onde parou no dia seguinte (o contador diário zera automaticamente ao mudar o dia).
• Gera 3 arquivos CSV (um por tipo) em FULL_SCAN_DIR (padrão full_scan/).

Opções:

• --type (obrigatório): carros | motos | caminhoes
• --out (obrigatório): caminho do CSV de saída
• --timeout (padrão 15): timeout por requisição (s)
• --retries (padrão 3): tentativas em falhas temporárias
• --backoff (padrão 0.5): fator de backoff exponencial entre tentativas
• --rate-delay (padrão 0.0): delay em segundos entre requisições (ex.: 0.1)
• --max-brands: limita quantidade de marcas (útil para testes)
• --max-models: limita quantidade de modelos por marca (útil para testes)
• --workers (padrão 1): número de requisições concorrentes (multithread)
• --token: cabeçalho X-Subscription-Token (obrigatório para v2 se aplicável)
• --reference: código do mês de referência (ex.: 308)

Exemplos

• Carros (amostra rápida para teste):

python fipe_crawler.py --type carros --out fipe_carros_sample.csv --max-brands 2 --max-models 3 --rate-delay 0.1 --workers 1 --token SEU_TOKEN --reference 308

• Motos (com mais tolerância a falhas):

python fipe_crawler.py --type motos --out fipe_motos.csv --timeout 20 --retries 5 --workers 1 --token SEU_TOKEN

• Caminhões (com delay para evitar rate limit):

python fipe_crawler.py --type caminhoes --out fipe_caminhoes.csv --rate-delay 0.15 --workers 1 --token SEU_TOKEN

Opções detalhadas

• --type: Tipo de veículo. Aceita carros, motos, caminhoes (mapeados para cars, motorcycles, trucks na API v2).
• --out: Caminho do CSV de saída.
• --timeout: Timeout por requisição.
• --retries e --backoff: Retentativas em erros temporários (429/5xx) com backoff exponencial.
• --rate-delay: Atraso entre requisições (ajuda a evitar rate limit).
• --max-brands / --max-models: Limites para testes rápidos.
• --workers: Concorrência (padrão 1). Aumente com cautela devido a limites diários.
• --token: Token v2 (se omitido, será lido de TOKEN no .env).
• --reference: Código da referência (se omitido, usa o mês atual; pode ser definido em REFERENCE no .env).
• --list-references: Lista todas as referências (imprime code,month) e encerra.
• --full-scan: Executa varredura completa (carros→motos→caminhoes) com limite diário e retomada automática.

Saída CSV

Colunas geradas:

tipo,codigo_marca,marca,codigo_modelo,modelo,codigo_ano,ano_modelo,combustivel,sigla_combustivel,codigo_fipe,mes_referencia,valor

Observação: valor vem no formato numérico sem o prefixo "R$"; trate a localidade conforme necessário. Os campos mapeiam a resposta v2 (brand, model, modelYear, fuel, fuelAcronym, codeFipe, referenceMonth, price).

Notas

• A API v2 usa X-Subscription-Token e possui limites (por ex., 500 req/dia). Informe --token (ou .env).
• Rodar o dataset completo pode levar tempo. Use --max-brands e --max-models para validar primeiro.
• Em caso de HTTP 429/5xx, o script tenta automaticamente novamente (--retries e --backoff).
• Concurrency: os preços por ano são buscados em paralelo. Por padrão --workers=1 para respeitar limites; aumente com cautela.

Logs no console

Durante a execução são emitidos logs padronizados para acompanhar o progresso:

• [START] início de export ou full scan com parâmetros
• [STAGE] avanço de etapa (tipo, marca, modelo, anos)
• [RESUME] retomada a partir de checkpoint (full scan)
• [CONT]/[NEXT] continuidade de índices de marca/modelo/ano
• [STATS] resumo de linhas processadas e uso diário
• [REF] referência utilizada (latest ou informada)

Troubleshooting

• Unauthorized (401/403): verifique TOKEN (CLI ou .env). Tokens inválidos ou ausentes causam erro.
• Too Many Requests (429): reduza --workers, aumente --rate-delay (ex.: 0.1–0.5), aumente --backoff e/ou --retries.
• Timeouts: aumente --timeout (ex.: 30) e --retries.
• Sem linhas no CSV: confira se há dados para a --reference usada; tente listar com --list-references e ajustar.
• Full scan pausou cedo: verifique DAILY_LIMIT e LIMIT_MARGIN no .env. O processo pausa quando remaining <= margin para evitar atingir o teto diário.

Fluxo com curl (informativo)

Você pode explorar a API FIPE (Parallelum) com curl para entender o fluxo antes de usar o script. Substitua os placeholders {...} pelos códigos obtidos na etapa anterior.

• Listar marcas (ex.: carros):

curl -s "https://fipe.parallelum.com.br/api/v2/cars/brands?reference=308" -H "X-Subscription-Token: SEU_TOKEN"

• Listar modelos de uma marca:

curl -s "https://fipe.parallelum.com.br/api/v2/cars/brands/{codigoMarca}/models?reference=308" -H "X-Subscription-Token: SEU_TOKEN"

• Listar anos de um modelo:

curl -s "https://fipe.parallelum.com.br/api/v2/cars/brands/{codigoMarca}/models/{codigoModelo}/years?reference=308" -H "X-Subscription-Token: SEU_TOKEN"

• Obter preço/detalhes para um ano específico:

curl -s "https://fipe.parallelum.com.br/api/v2/cars/brands/{codigoMarca}/models/{codigoModelo}/years/{codigoAno}?reference=308" -H "X-Subscription-Token: SEU_TOKEN"

Notas:

• Para motos e caminhões, substitua cars por motorcycles ou trucks na URL.
• Em Windows/PowerShell, curl pode ser um alias de Invoke-WebRequest. Se preferir, use curl.exe explicitamente.
• A resposta é JSON; para visualizar melhor, você pode usar utilitários como jq (Linux/macOS) ou formatadores online.

Exemplos no PowerShell (Windows)

• Executar com Python do sistema usando o launcher do Windows:

py .\fipe_crawler.py --list-references
py .\fipe_crawler.py --type carros --out .\fipe_carros.csv
py .\fipe_crawler.py --full-scan

• Definir variáveis de ambiente temporárias no PowerShell e executar:

$env:TOKEN = "SEU_TOKEN"
$env:REFERENCE = "latest"   # ou um código como 308
py .\fipe_crawler.py --type motos --out .\fipe_motos.csv

• Quebra de linha em comandos longos (use acento grave/backtick `):

py .\fipe_crawler.py \
  --type caminhoes \
  --out .\fipe_caminhoes.csv \
  --timeout 30 \
  --retries 5 \
  --rate-delay 0.2 \
  --workers 1

Observação: o .env na raiz é carregado automaticamente; variáveis via CLI têm precedência.

Como contribuir

1. Clone ou faça fork do repositório.

2. Crie um ambiente virtual e instale dependências:

   • PowerShell (Windows):

   py -m venv .venv
   .\.venv\Scripts\Activate.ps1
   pip install -r requirements.txt

   • Bash (Linux/macOS):

   python3 -m venv .venv
   source .venv/bin/activate
   pip install -r requirements.txt

3. Execute os comandos de uso para validar mudanças.

4. Siga a estrutura modular (fipecrawler/) e mantenha logs padronizados.

5. Abra um PR descrevendo claramente mudanças, motivo e impacto.