projeto_grande_vitoria_empresas

<div align="center"> # 🗺️ Dataset de Empresas da Grande Vitória (ES) ### A base aberta mais completa de empresas ativas do Espírito Santo — pronta para prospecção, pesquisa e análise de mercado. **344 mil empresas ativas** de **7 municípios**, cruzando dados cadastrais, **sócios**, jurídicos, sanções, dívida ativa e infrações ambientais — tudo de **fontes públicas oficiais**. Com **dashboard**, **API REST**, **MCP** (Claude) e **classificação de leads**. <br> [](#) [](#) [](#) [](#-consumir-o-dataset) [](#-consumir-o-dataset) [](#-projeto-em-construção) <br> <a href="https://github.com/sponsors/brunokobi"> <img src="https://img.shields.io/badge/%E2%9D%A4%EF%B8%8F%20Apoiar%20este%20projeto-GitHub%20Sponsors-ea4aaa?style=for-the-badge&logo=githubsponsors&logoColor=white" alt="Apoiar no GitHub Sponsors" height="42"> </a> _{Projeto aberto e sem fins lucrativos — seu apoio custeia a atualização mensal das bases.} <br><br> ### ⭐ Se este projeto te for útil, **deixe uma estrela** — leva 1 segundo, é de graça e ajuda demais a dar visibilidade ao trabalho! </div> --- ## ⚡ Começar em 1 comando O dataset é distribuído como **GitHub Release** (não fica versionado no repo — mantém tudo leve). O script de setup usa o [uv](https://docs.astral.sh/uv/) para criar o ambiente com um Python 3.12 isolado (instalando o próprio uv se preciso), instalar dependências e **baixar o dataset** — **não precisa ter Python pré-instalado**, nem depende da versão que o sistema operacional já traz. **Linux, macOS ou WSL:** ```bash git clone https://github.com/brunokobi/projeto_grande_vitoria_empresas.git cd projeto_grande_vitoria_empresas bash setup.sh source .venv/bin/activate uvicorn api:app # http://localhost:8000 ``` **Windows (PowerShell nativo, sem precisar de WSL):** ```powershell git clone https://github.com/brunokobi/projeto_grande_vitoria_empresas.git cd projeto_grande_vitoria_empresas powershell -ExecutionPolicy Bypass -File setup.ps1 .venv\Scripts\Activate.ps1 uvicorn api:app # http://localhost:8000 ``` Pronto: **dashboard** em `http://localhost:8000`, **API** em `/docs`, e o **MCP** detectado pelo Claude Code (`.mcp.json`). > **Nota (LGPD).** Os dados vêm de fontes públicas oficiais, mas o dataset consolida dados de pessoas (nomes de sócios, CPF mascarado, endereços). Use de forma responsável e conforme a LGPD. --- ## 📸 Telas <div align="center"> **Dashboard — lista, filtros e classificação de leads** <img src="docs/dashboard.png" alt="Dashboard" width="100%"> **Visão 360º da empresa** — cadastro, sócios + rede, pendências detalhadas e mapa <img src="docs/empresa-360.png" alt="Visão 360º da empresa" width="70%"> </div> --- ## 🚧 Projeto em construção Em desenvolvimento ativo. Estado atual: | Componente | Status | |---|---| | Cadastro (Receita) · **Sócios** · JUCEES | ✅ pronto (344k empresas · 231k sócios) | | Dívida ativa **PGFN** (detalhada) | ✅ pronto | | Sanções federais **CEIS/CNEP** + estaduais **TCEES** | ✅ pronto | | Infrações **IBAMA** (detalhadas) | ✅ pronto | | Geocodificação (mapa, OpenStreetMap) | 🚧 em processamento — **previsão ~30/07/2026** | | Processos judiciais (DataJud/CNJ, TJES) | 🚧 em processamento — **previsão ~20/09/2026** | | Contato & redes sociais (WhatsApp, site, Instagram…) | 🧪 implementado | | Dashboard · API · MCP · export Excel/PDF · **classificação de leads** | ✅ funcionais | > ⏳ As previsões acima são **estimativas** com base no ritmo atual — essas duas > etapas dependem de APIs públicas com limite de requisições (OpenStreetMap ~1/s; > CNJ com throttling), por isso levam dias/semanas. O restante do dataset já está > completo e disponível; geo e processos vão sendo incorporados conforme concluem. --- ## 💼 O que você recebe | | | |---|---| | 🏢 **Cadastro** | CNPJ, razão social, CNAE (por nome), porte, regime, capital, endereço, situação | | 👥 **Sócios + rede** | Quadro societário (nome, qualificação, faixa etária) e **em quais outras empresas o mesmo sócio aparece** | | ⚖️ **Situação jurídico-fiscal detalhada** | Dívida ativa (tipo de tributo, ajuizamento, risco), sanções federais/estaduais (fundamentação), infrações IBAMA (valor, gravidade), processos | | 🧭 **Enriquecimento** | Geolocalização (mapa) e contato/redes sociais | | 🎯 **Classificação de leads** | Questionário por objetivo comercial → score 0–100 (🔥 Quente / 🙂 Morno / ❄️ Frio) | | 🔌 **Acesso** | Dashboard web, API REST, servidor MCP (Claude), export Excel e PDF | --- ## 🔗 Fontes de dados cruzadas Tudo cruzado pelo **CNPJ**, exclusivamente de **fontes públicas oficiais**: | Fonte | O que agrega | Status | |---|---|:--:| | **Receita Federal** (CNPJ) | Cadastro, **sócios**, CNAE, porte, capital, endereço | ✅ | | **JUCEES** (dados.es.gov.br) | NIRE, constituição, natureza jurídica | ✅ | | **PGFN** | Dívida ativa (tipo de tributo, valor, ajuizamento) | ✅ | | **CGU** — Portal da Transparência | Sanções federais **CEIS/CNEP** (fundamentação legal) | ✅ | | **TCEES** | Sanções estaduais (processo/deliberação) | ✅ | | **IBAMA** | Infrações ambientais (valor da multa, gravidade, situação) | ✅ | | **OpenStreetMap** | Geolocalização (latitude/longitude) | 🚧 | | **DataJud / CNJ** | Processos judiciais (TJES) | 🚧 | | IEMA-ES · RAIS/CAGED | Ambiental estadual · nº de empregados | 🔭 planejado | > A construção/atualização do dataset é feita por um pipeline de extração mantido em repositório separado. Este é o **produto de consumo**. --- ## 🖥️ Consumir o dataset Lógica de consulta compartilhada (`src/dataset_queries.py`) entre dashboard, API e MCP — todos leem o SQLite em **somente-leitura**. ### Dashboard web `uvicorn api:app` → **http://localhost:8000**. Filtros (segmento CNAE, município, porte, regime, tipo de pendência, capital, contato/redes, busca), **visão 360º** por empresa com **cards expansíveis** (dívida, sanção, infração e sócios detalhados) + mapa, **classificação de leads** (questionário) e **export Excel/PDF**. ### API REST (FastAPI) — docs em `/docs` - `GET /estatisticas` · `GET /segmentos` - `GET /empresas` — busca com filtros (município, `cnae_prefix`, porte, regime, `socio` (nome), `tem_pendencia`, `com_processos`/`com_sancoes`/`com_ambiental`/`com_divida`, `com_telefone`/`com_email`/`com_whatsapp`/`com_rede_social`, capital, ordenação, paginação) - `GET /empresas/{cnpj}` — visão 360º (cadastro, sócios+rede, pendências detalhadas, geo) - `GET /classificar` — pontua e ranqueia leads por objetivo comercial - `GET /export/empresas.xlsx` · `GET /export/empresas.pdf` ### Servidor MCP Ferramentas `estatisticas`, `buscar_empresas`, `obter_empresa`, `classificar_empresas` para o Claude e outros clientes MCP. O `.mcp.json` é detectado automaticamente após o `setup.sh`. 📘 **Tutorial completo de conexão** (Claude Desktop, Claude Code, Cursor, Windsurf, VS Code/Copilot, Cline): **[MCP.md](MCP.md)**. --- ## 💛 Apoie o projeto [](https://github.com/sponsors/brunokobi) · níveis em [](SPONSORS.md) ## 💬 Contato, sugestões e contribuições | Quero... | Como | |---|---| | 🔗 Sugerir nova fonte de dados | [](https://github.com/brunokobi/projeto_grande_vitoria_empresas/issues/new?template=nova-fonte.yml) | | 💡 Sugestão, melhoria ou pedido | [](https://github.com/brunokobi/projeto_grande_vitoria_empresas/issues/new?template=sugestao.yml) | | 🐞 Problema ou reclamação | [](https://github.com/brunokobi/projeto_grande_vitoria_empresas/issues/new?template=problema.yml) | | 📧 Falar direto | [](mailto:brunokobi2@hotmail.com) | | 🌐 Site / portfólio | [](https://brunokobi.netlify.app) | --- <div align="center"> _{Feito com 💛 no Espírito Santo · Dados de fontes públicas oficiais · Use conforme a LGPD} </div>