Argos
CLI que transforma uma busca no Google Maps em lista de leads em CSV
- Python
- DataForSEO API
- geopy
- OpenStreetMap Nominatim
- Rich
- Requests
- CSV
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.

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.

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.

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.

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.
// screenshots