FIPE Data Pipeline

Coleta e processa dados históricos de preços de veículos da Tabela FIPE para PostgreSQL.
Parte do fipe.chat — os dados que a FIPE tem, a clareza que ela nunca deu.

Requisitos

• Bun — brew install oven-sh/bun/bun
• Docker

Início Rápido

cp .env.example .env
docker compose up -d   # PostgreSQL
bun install            # dependências
bun run db:push        # schema
bun run crawl          # crawl

Comandos

bun install            # Instalar dependências
bun run db:push        # Criar/atualizar schema
bun run crawl          # Executar crawler
bun run status         # Estatísticas do banco
bun run classify       # Classificar modelos via AI
bun run backup         # Backup (pg_dump) para storage S3/R2 com retenção
bun run restore-drill  # Restaura o último backup num banco temporário e valida
bun run lint           # Verificar código
bun run format         # Formatar código
bun run typecheck      # Verificar tipos

Uso

bun run crawl                                    # ano atual, todos os meses
bun run crawl -- --year 2024                     # ano específico
bun run crawl -- --year 2020-2024                # range de anos
bun run crawl -- --year 2020,2022,2024           # anos específicos
bun run crawl -- --month 1-6                     # range de meses
bun run crawl -- --year 2023-2024 --month 1,6,12 # combinar filtros
bun run crawl -- --brand 59                      # marca específica (59 = VW)
bun run crawl -- --brand 21,22,59                # múltiplas marcas
bun run crawl -- --brand 59 --model 5940         # modelo específico
bun run crawl -- --reference 328                 # tabela de referência específica
bun run crawl -- --classify                      # classificar modelos novos via AI
bun run crawl -- --force                         # re-buscar tudo

bun run status                                   # estatísticas do banco
bun run classify                                 # classificar modelos sem segmento
bun run classify -- --dry-run                    # preview da classificação

Docker

docker build -t fipe-crawler .
docker run -d --name fipe --env-file .env fipe-crawler

docker exec fipe bun src/index.ts crawl --brand 25 --year 2024 --month 6
docker exec fipe bun src/index.ts status

Configuração

DATABASE_URL=postgres://postgres:postgres@localhost:5433/fipe
RATE_LIMIT_MS=800        # Delay mínimo entre requests (ms)
MAX_THROTTLE_MS=5000     # Delay máximo quando rate limited (ms)
MAX_RETRIES=3
ANTHROPIC_API_KEY=       # Para classificação de segmentos via AI (opcional)

# Backup para storage S3-compatível (opcional; usado por backup/restore-drill)
R2_ACCESS_KEY_ID=
R2_SECRET_ACCESS_KEY=
R2_ENDPOINT=             # ex: https://<account>.r2.cloudflarestorage.com
R2_BUCKET=

Schema

flowchart LR
    reference_tables --> prices
    brands --> models --> model_years --> prices

Schema SQL completo em initial.sql.

Fonte de Dados

Estes dados são públicos e oficiais, disponibilizados pela Fundação Instituto de Pesquisas Econômicas (FIPE).

A Tabela FIPE é a referência de preço médio de veículos mais utilizada no Brasil. Os dados são coletados mensalmente junto a concessionárias, revendedoras e fabricantes em todo o país.

Contribuidores