Pular para o conteúdo
~/rafael-ferreira

Argos

CLI que transforma uma busca no Google Maps em lista de leads em CSV

  • Python
  • DataForSEO API
  • geopy
  • OpenStreetMap Nominatim
  • Rich
  • Requests
  • CSV
Capa do projeto Argos

O Argos é uma ferramenta de linha de comando que transforma uma busca no Google Maps em uma lista de leads. Você informa o tipo de empresa e a região (um estado, uma cidade ou um bairro) e recebe cada empresa encontrada com endereço, telefone, nota, site, horário e coordenadas, em uma tabela no terminal e em um CSV pronto para planilha ou CRM.

Escrevi o Argos para levantar os primeiros leads do Markmedi. Antes de vender um sistema para clínicas, eu precisava saber quais clínicas existiam em cada região e como falar com elas. Fazer isso à mão é abrir o mapa, copiar nome e telefone um por um e arrumar tudo depois em uma planilha. O Argos faz o mesmo com um comando, e a lista sai no formato que a prospecção outbound usa.

Argos no terminal: resumo da busca por clínicas médicas em Pinheiros, barra de progresso e tabela de resultados com dados de exemplo

Como funciona

São cinco passos em um único arquivo Python. Os parâmetros vêm de flags ou de perguntas no terminal. Se houver um bairro, o Nominatim do OpenStreetMap o converte em latitude e longitude. A busca é uma única requisição à API de Google Maps do DataForSEO, que devolve até 700 empresas. Cada resultado é normalizado e, por fim, exibido e gravado em CSV. Não há navegador automatizado nem leitura de HTML: os dados vêm de uma API paga, o que deixa a ferramenta pequena e estável.

Cinco passos: entrada, geocodificação opcional do bairro, busca no DataForSEO, normalização dos campos e entrega em tabela e CSV

Cidade inteira ou raio em torno de um bairro

Para dimensionar um mercado, a busca cobre uma cidade ou um estado. Para prospecção local, basta o nome do bairro e um raio em quilômetros: o Argos descobre as coordenadas sozinho. No modo interativo, cidade e estado são digitados como se escreve normalmente, com acento ou só a sigla, e a ferramenta converte para o formato que a API exige.

Dois modos de busca: cidade ou estado inteiro com --location, ou raio em torno de um bairro com --neighborhood e --radius

Dados que já saem limpos

O Google Maps mostra o endereço como uma linha de texto. O Argos a divide em rua, complemento, cidade, estado e CEP, formata o horário de funcionamento por dia da semana e mantém nota e número de avaliações em colunas próprias, o que permite ordenar e filtrar a lista antes de abordar alguém. São 15 colunas, uma empresa por linha. A divisão espera o formato brasileiro de endereço; fora dele, a linha completa continua disponível.

Um resultado do Google Maps em texto livre à esquerda e, à direita, os mesmos dados separados nas 15 colunas do CSV

Detalhes de uso

  • Primeira execução sem atrito: se não houver credenciais, a ferramenta pede login e senha da API e grava no .env, que já está fora do Git.
  • Dois modos: sem flags, pergunta tudo; com --keyword, roda direto, o que serve para scripts e buscas repetidas.
  • Espera visível: a requisição roda em uma thread enquanto o terminal mostra progresso e tempo decorrido.
  • Erros ditos com clareza: bairro não encontrado, erro da API e resposta inesperada viram mensagens curtas em vez de um stack trace.

O nome vem de Argos Panoptes, o gigante de cem olhos da mitologia grega. O código é aberto, sob licença MIT, e serve para qualquer tipo de negócio: academias, restaurantes, escritórios de advocacia, pet shops.

Galeria

Outros projetos

Capa do projeto Markmedi
markmedi.com · privado ★ destaque

Markmedi

Meu projeto principal: agenda, prontuário, telemedicina, financeiro, CRM e marketing para clínicas, num monólito modular em Laravel e Vue com filas, tempo real e criptografia por clínica.

  • Laravel
  • Vue 3
  • Inertia.js
  • TypeScript
  • Tailwind CSS
Capa do projeto Plataforma B2B para venda de ingressos e cursos
plataforma-b2b-ingressos-e-cursos · privado ★ destaque

Plataforma B2B para venda de ingressos e cursos

Plataforma B2B que vende ingressos e cursos, valida a entrada em eventos com QR assinado e check-in offline e deixa a empresa comprar licenças e acompanhar o progresso de cada colaborador.

  • Laravel
  • Vue 3
  • Inertia.js
  • TypeScript
  • Tailwind CSS