Google Maps Lead Generator

A full-stack lead generation tool that searches for local businesses using the Google Places API (New) and exports results as CSV.

Features

• Search by business type/keyword with location and radius
• Filter by minimum rating
• Sortable results table with business name, rating, reviews, phone, website, and address
• Export lead lists as CSV
• Modern UI built with React, shadcn/ui, and Tailwind CSS

Prerequisites

• Python 3.11+
• Node.js 18+ and npm
• Google Cloud account with a valid API key

Google Cloud Setup

1. Go to the Google Cloud Console
2. Create a new project (or select an existing one)
3. Enable the following APIs:
   • Places API (New) — Enable here
   • Geocoding API — Enable here
4. Go to APIs & Services > Credentials and create an API key
5. Copy the API key for the next step

Getting Started

1. Clone and configure environment

cp .env.example .env

Open .env and paste your Google Maps API key:

GOOGLE_MAPS_API_KEY=your_actual_api_key_here

2. Start the backend

cd backend
pip install -r requirements.txt
cd ..
uvicorn backend.main:app --reload

The API will be available at http://localhost:8000. API docs at http://localhost:8000/docs.

3. Start the frontend

cd frontend
npm install
npm run dev

The app will be available at http://localhost:5173.

Project Structure

├── .env.example          # Environment variable template
├── .gitignore
├── README.md
├── backend/
│   ├── main.py           # FastAPI app entry point
│   ├── requirements.txt
│   ├── models/
│   │   └── schemas.py    # Pydantic request/response models
│   ├── routers/
│   │   └── search.py     # Search and export API endpoints
│   └── services/
│       ├── geocoding.py  # Google Geocoding API client
│       └── places.py     # Google Places API (New) client
└── frontend/
    ├── package.json
    ├── vite.config.ts
    ├── components.json   # shadcn/ui config
    └── src/
        ├── App.tsx       # Main application layout
        ├── api/
        │   └── client.ts # API client
        ├── components/
        │   ├── ui/       # shadcn/ui components
        │   ├── SearchForm.tsx
        │   ├── ResultsTable.tsx
        │   └── ExportButton.tsx
        └── types.ts      # TypeScript interfaces

API Endpoints

Method	Endpoint	Description
POST	/api/search	Search for businesses
GET	/api/export/{search_id}	Export search results as CSV

POST /api/search

Request body:

{
  "keyword": "plumber",
  "location": "Denver, CO",
  "radius_km": 10,
  "min_rating": 3.5,
  "max_results": 60
}

GET /api/export/{search_id}

Returns a CSV file download with columns: Name, Address, Phone, Website, Rating, Reviews, Business Hours, Google Maps URL, Type.

Cost Considerations

This app uses the Google Places API (New) Text Search endpoint. The field mask used triggers the Text Search Enterprise SKU (due to phone, website, rating, and hours fields). Key points:

• Each search page (20 results) is one billable request
• A max search (60 results) uses up to 3 requests
• Results are cached server-side so CSV export does not re-query
• Google offers a $200/month free credit for Maps Platform usage

See Google Maps Platform pricing for current rates.