Mapbox Google Maps Migration

# Google Maps to Mapbox GL JS Migration Guide

Quick reference for migrating from Google Maps Platform to Mapbox GL JS with API equivalents and patterns.

## Critical Differences

| Aspect             | Google Maps             | Mapbox GL JS              |
| ------------------ | ----------------------- | ------------------------- |
| **Coordinates**    | `{lat, lng}` objects    | `[lng, lat]` arrays       |
| **Philosophy**     | Imperative (objects)    | Declarative (data-driven) |
| **Rendering**      | DOM elements            | WebGL (much faster)       |
| **Performance**    | Slow with 500+ markers  | Fast with 10,000+ points  |
| **Initialization** | `new google.maps.Map()` | `new mapboxgl.Map()`      |

## Quick Migration Checklist

✅ Install `mapbox-gl` package
✅ Get Mapbox access token
✅ Swap coordinate order (lat,lng → lng,lat)
✅ Replace Google Maps API with Mapbox equivalents
✅ Use Symbol layers for 100+ markers (not HTML markers)
✅ Add clustering for 500+ points
✅ Update geocoding to Mapbox Geocoding API
✅ Test all functionality

## API Equivalents

### Map Initialization

```javascript
// Google Maps
const map = new google.maps.Map(document.getElementById('map'), {
  center: { lat: 37.7749, lng: -122.4194 },
  zoom: 12
});

// Mapbox GL JS
mapboxgl.accessToken = 'pk.your_token';
const map = new mapboxgl.Map({
  container: 'map',
  style: 'mapbox://styles/mapbox/streets-v12',
  center: [-122.4194, 37.7749], // Note: [lng, lat]
  zoom: 12
});
```

### Individual Markers (< 50 points)

```javascript
// Google Maps
const marker = new google.maps.Marker({
  position: { lat: 37.7749, lng: -122.4194 },
  map: map
});

// Mapbox (equivalent approach)
const marker = new mapboxgl.Marker().setLngLat([-122.4194, 37.7749]).addTo(map);
```

### Many Markers (100+ points) - Performance Critical

```javascript
// ❌ Google Maps: DOM-based (slow with 500+ markers)
locations.forEach((loc) => {
  new google.maps.Marker({
    position: { lat: loc.lat, lng: loc.lng },
    map: map
  });
});

// ✅ Mapbox: WebGL-based (fast with 10,000+ points)
map.addSource('points', {
  type: 'geojson',
  data: {
    type: 'FeatureCollection',
    features: locations.map((loc) => ({
      type: 'Feature',
      geometry: { type: 'Point', coordinates: [loc.lng, loc.lat] }
    }))
  }
});

map.addLayer({
  id: 'points',
  type: 'symbol',
  source: 'points',
  layout: {
    'icon-image': 'marker-15'
  }
});
```

**Performance Note:** Google Maps renders ALL markers as DOM elements (even with Data Layer). Mapbox uses WebGL for Symbol/Circle layers = 10-100x faster for large datasets.

### Clustering (500+ points)

```javascript
// Google Maps (requires MarkerClusterer library)
import MarkerClusterer from '@googlemaps/markerclustererplus';
const clusterer = new MarkerClusterer(map, markers);

// Mapbox (built-in)
map.addSource('points', {
  type: 'geojson',
  data: geojson,
  cluster: true,
  clusterRadius: 50
});
```

### Info Windows / Popups

```javascript
// Google Maps
const infowindow = new google.maps.InfoWindow({
  content: '<h3>Title</h3>'
});
infowindow.open(map, marker);

// Mapbox
const popup = new mapboxgl.Popup().setHTML('<h3>Title</h3>').setLngLat([-122.4194, 37.7749]).addTo(map);

// Or attach to marker
marker.setPopup(popup);
```

### Events

```javascript
// Google Maps
marker.addListener('click', () => {
  /* ... */
});
map.addListener('click', (e) => {
  const lat = e.latLng.lat();
  const lng = e.latLng.lng();
});

// Mapbox
marker.on('click', () => {
  /* ... */
});
map.on('click', (e) => {
  const [lng, lat] = [e.lngLat.lng, e.lngLat.lat];
});
```

### Geocoding

```javascript
// Google Maps
const geocoder = new google.maps.Geocoder();
geocoder.geocode({ address: '1600 Amphitheatre Parkway' }, (results) => {
  map.setCenter(results[0].geometry.location);
});

// Mapbox
fetch(
  `https://api.mapbox.com/search/geocode/v6/forward?q=1600+Amphitheatre+Parkway&access_token=${mapboxgl.accessToken}`
)
  .then((r) => r.json())
  .then((data) =