Skip to content
~/rafael-ferreira

Argos

A CLI that turns a Google Maps search into a CSV list of leads

  • Python
  • DataForSEO API
  • geopy
  • OpenStreetMap Nominatim
  • Rich
  • Requests
  • CSV
Cover of the Argos project

Argos is a command-line tool that turns a Google Maps search into a list of leads. You give it a business type and a region (a state, a city or a neighborhood) and get back every business it finds with address, phone, rating, website, opening hours and coordinates, as a table in the terminal and as a CSV ready for a spreadsheet or CRM.

I wrote Argos to source the first leads for Markmedi. Before selling software to clinics, I needed to know which clinics existed in each region and how to reach them. Doing that by hand means opening the map, copying names and phone numbers one by one and cleaning it all up in a spreadsheet afterwards. Argos does the same with a single command, and the list comes out in the format outbound prospecting uses.

Argos in the terminal: search summary for medical clinics in Pinheiros, a progress bar and a results table with sample data

How it works

It is five steps in a single Python file. Parameters come from flags or from prompts in the terminal. If a neighborhood is given, OpenStreetMap's Nominatim converts it to latitude and longitude. The search is a single request to DataForSEO's Google Maps API, which returns up to 700 businesses. Each result is normalized and, finally, displayed and written to CSV. There is no browser automation and no HTML scraping: the data comes from a paid API, which keeps the tool small and stable.

Five steps: input, optional neighborhood geocoding, DataForSEO search, field normalization and output as a table and CSV

A whole city or a radius around a neighborhood

To size a market, the search covers a city or a state. For local prospecting, all it takes is the neighborhood name and a radius in kilometers: Argos works out the coordinates on its own. In interactive mode, city and state are typed the way you would normally write them, with accents or just the state abbreviation, and the tool converts them to the format the API expects.

Two search modes: a whole city or state with --location, or a radius around a neighborhood with --neighborhood and --radius

Data that comes out clean

Google Maps shows the address as a single line of text. Argos splits it into street, address line 2, city, state and postal code (CEP), formats the opening hours by day of the week and keeps the rating and review count in their own columns, so you can sort and filter the list before reaching out to anyone. That is 15 columns, one business per row. The split expects the Brazilian address format; outside of it, the full line is still available.

A Google Maps result as free text on the left and, on the right, the same data split into the 15 CSV columns

Usage details

  • Frictionless first run: if there are no credentials, the tool asks for the API login and password and saves them to .env, which is already ignored by Git.
  • Two modes: with no flags, it asks for everything; with --keyword, it runs straight through, which suits scripts and repeated searches.
  • Visible waiting: the request runs in a thread while the terminal shows progress and elapsed time.
  • Clearly stated errors: neighborhood not found, API errors and unexpected responses become short messages instead of a stack trace.

The name comes from Argus Panoptes, the hundred-eyed giant of Greek mythology. The code is open source under the MIT license and works for any kind of business: gyms, restaurants, law firms, pet shops.

Gallery

Other projects

Cover of the Markmedi project
markmedi.com · private ★ featured

Markmedi

My main project: scheduling, medical records, telemedicine, finance, CRM and marketing for clinics, in a modular Laravel and Vue monolith with queues, real-time updates and per-clinic encryption.

  • Laravel
  • Vue 3
  • Inertia.js
  • TypeScript
  • Tailwind CSS
Cover of the B2B platform for ticket and course sales project
b2b-ticketing-and-courses-platform · private ★ featured

B2B platform for ticket and course sales

A B2B platform that sells tickets and courses, validates event entry with signed QR codes and offline check-in, and lets companies buy licenses and track each employee's progress.

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