# Geocoding Debug Guide

## How the Geocoding System Works

The map now uses **real geocoding** via the Nominatim API (OpenStreetMap) to get precise coordinates for office addresses.

### Process Flow:

1. **Address Normalization**: Cleans addresses by removing metadata like "Main office", "2nd Floor", etc.
2. **Geocoding**: Sends cleaned address to Nominatim API
3. **Caching**: Stores geocoded coordinates to avoid repeated API calls
4. **Rate Limiting**: Respects Nominatim's 1 request/second limit
5. **Marker Placement**: 
   - Single offices: placed at exact geocoded location
   - Shared offices: spread in a circle around the location for visibility

### Debugging in Browser Console

After searching for a postal code, check the browser console (F12) for:

```javascript
// You should see output like:
Original address: 2nd Floor, City Hall
1 Sir Winston Churchill Square
Edmonton AB  T5J 2R7

Cleaned address for geocoding: 1 Sir Winston Churchill Square, Edmonton AB  T5J 2R7, Canada

✓ Geocoded "1 Sir Winston Churchill Square, Edmonton AB  T5J 2R7, Canada" to: {lat: 53.5440376, lng: -113.4897656}
  Display name: Sir Winston Churchill Square, 9918, Downtown, Central Core, Edmonton, Alberta, T5J 5H7, Canada
```

### Expected Behavior

**For Edmonton postal codes (T5J, T5K, etc.):**
- Municipal reps → Should appear at City Hall (Sir Winston Churchill Square)
- Provincial MLAs → Should appear at their constituency offices (geocoded addresses)
- Federal MPs → May appear at Parliament Hill in Ottawa OR local Edmonton offices

**For Calgary postal codes (T1Y, T2P, etc.):**
- Should appear at various Calgary locations based on constituency offices

**For other Alberta cities:**
- Should appear at the actual street addresses in those cities

### Why Some Clustering is Normal

If you see multiple markers in the same area, it could be because:

1. **Legitimately Shared Offices**: Multiple city councillors work from City Hall
2. **Same Building, Different Offices**: Legislature has multiple MLAs
3. **Geocoding to Building vs Street**: Some addresses geocode to the building center

The system now **spreads these markers in a circle** around the shared location so you can click each one individually.

### Testing Different Locations

Try these postal codes to verify geographic diversity:

- **Edmonton Downtown**: T5J 2R7 (should show City Hall area)
- **Calgary**: T1Y 1A1 (should show Calgary locations)
- **Red Deer**: T4N 1A1 (should show Red Deer locations)
- **Lethbridge**: T1J 0A1 (should show Lethbridge locations)

### Geocoding Cache

The system caches geocoding results in browser memory. To reset:
- Refresh the page (F5)
- Or run in console: `geocodingCache.clear()`

### API Rate Limiting

Nominatim allows 1 request per second. For 10 representatives with offices:
- Estimated time: 10-15 seconds to geocode all addresses
- Cached results are instant

### Fallback Behavior

If geocoding fails for an address, the system falls back to:
1. City-level coordinates (from Alberta cities lookup table)
2. District-based approximation
3. Government level default (Legislature, City Hall, etc.)

This ensures every representative has a marker, even if precise geocoding fails.