# Google Places API setup

## 1. Put your key in `.env` (never commit it)

```bash
cd ~/neighborhood-monopoly-map
cp .env.example .env
# edit .env — one line:
# GOOGLE_MAPS_API_KEY=paste_your_key_here
```

Do **not** paste the key into chat.

## 2. Google Cloud checklist

1. [Google Cloud Console](https://console.cloud.google.com/) → project with **billing** enabled  
2. Enable **Places API (New)**  
3. Credentials → API key  
4. Restrict key (recommended):  
   - Application: IP `127.0.0.1` for local only, or none while testing  
   - API restriction: **Places API (New)** only  
5. Confirm free monthly caps on [pricing](https://developers.google.com/maps/billing-and-pricing/pricing) (Text Search Pro often **5,000 free**/month)

## 3. Run

```bash
# stop anything else on 4321 first
cd ~/neighborhood-monopoly-map
python3 server.py
```

Open **http://127.0.0.1:4321/**

- Header should say **live** when an API key is configured  
- `/api/health` → `"apiKeyConfigured": true`  
- Trade **Cleaning** + town **Warner Robins** → real businesses  

## 4. What gets billed

Only **Refresh** runs a Places scan. Town/trade changes do not call Google by themselves.

Results are cached in `.cache/` for 7 days by default. Repeating the same town/trade/limit reads the local cache instead of spending another Places request. Prefer one scan per town while selling.

## 5. Fallback

If key missing or API errors, UI uses **sample fallback** competitors so the map still works.