Setup guide

API keys

Real runs need two keys: Google Places for discovery and OpenAI for contact extraction. Put them in your .env as GOOGLE_PLACES_API_KEY and OPENAI_API_KEY, and set MOCK_API=false. Mock mode works without either.

Google Places API

GOOGLE_PLACES_API_KEY
  1. Go to console.cloud.google.com and create a new project (or use an existing one).
  2. Enable “Places API (New)” specifically — not the classic “Places API”. They’re different products in Google’s marketplace.
  3. Create an API key under Credentials.
  4. Restrict the key to “Places API (New)” only, via API restrictions. This limits the damage if the key ever leaks.
  5. Set up a budget alert: Billing → Budgets & alerts → create a budget with a low threshold (e.g. $1) and email alerts at 50 / 90 / 100%.

    Google only alerts you — it doesn’t auto-stop spending. This is an early warning, not a hard cap.

  6. Enable billing on the project. Google requires a card, but there’s a free monthly quota; check current limits at cloud.google.com/maps-platform/pricing.

    The free tier size depends on which fields you request — fields like rating or reviewCount can push you into a lower-quota tier.

  7. Recommended: use a prepaid or virtual card with a low balance instead of your main card, as an extra hard limit beyond the alert.
  8. Normal LeadPuppet usage (hundreds of leads a month) is very unlikely to exceed the free tier — one real run of 300 leads used about 20 queries.

OpenAI API

OPENAI_API_KEY
  1. Go to platform.openai.com and create an account if needed.
  2. API Keys → Create new secret key.
  3. Add a payment method. OpenAI has no permanent free tier, but the real cost is cents — about $0.10 for 150 leads generated, using gpt-4o-mini.
  4. Recommended: set a spend limit in Settings → Limits (a low monthly cap, e.g. $5) as a safety net.
  5. The same prepaid / virtual card recommendation as above applies here too.

A note on safety

Both Google and OpenAI can be configured with spend alerts, but neither guarantees a hard stop on spending by default. Use a low-limit prepaid or virtual card when setting these up, so your maximum possible exposure is capped regardless of any alert delay.

Back to the quick start