---
id: TASK-6
title: Integrate Google Geocoding and Places lead discovery
status: To Do
assignee: []
created_date: '2026-06-03 19:12'
labels:
  - mvp
  - integrations
  - leads
dependencies:
  - TASK-5
references:
  - PRD.md
priority: high
ordinal: 6000
---

## Description

<!-- SECTION:DESCRIPTION:BEGIN -->
Connect the campaign runner to Google Geocoding and Google Places. The system geocodes German postal codes, searches local businesses by category or custom niche within the configured radius, applies per-run limits, and stores source-backed lead records without sending outreach.
<!-- SECTION:DESCRIPTION:END -->

## Acceptance Criteria
<!-- AC:BEGIN -->
- [ ] #1 German PLZ values are geocoded to coordinates and cached on the campaign or run
- [ ] #2 Google Places searches use category mappings or custom niche text plus configured radius
- [ ] #3 Lead records store Place ID, business name, address, category, website, phone, rating metadata for internal use, and source timestamps where available
- [ ] #4 Runs respect max new leads and never start if another agent run is already active
- [ ] #5 API failures, empty results, skipped duplicates, and skipped blacklisted entities are visible in run logs
<!-- AC:END -->

## Implementation Plan

<!-- SECTION:PLAN:BEGIN -->
1. Define category-to-Places-query mappings for the initial MVP categories.
2. Add Google Geocoding integration with Germany-focused requests.
3. Add Google Places search integration using stored campaign settings.
4. Persist discovered leads with source metadata and run linkage.
5. Add run-level logging for success, empty, duplicate, blacklisted, and error cases.
<!-- SECTION:PLAN:END -->